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III. FORMATTING FACJUTIES 
NROFF AND TROFF USER'S MANUAL 


1. Introduction 


nalJjS P rocess °7’ nroff and troff > under the UNIX operating system format text for typewriter-like tenni- 
w? hSfJrf? Phototypesetter respectively Both nroff and troff processors accept lines of text interspeSd 
ith lines of format control information. They format the text into a printable, paginated document having a 
user-designed style. The nroff and troff formatters offer unusual freedom in document styling including 

o Arbitrary style headers and footers 


• Arbitrary style footnotes 

• Multiple automatic sequence numbering for paragraphs and sections 

• Multiple column output 

• Dynamic font and point-size control 


Arbitrary horizontal and vertical local motions at any point 


• Overstriking, bracket construction, and line drawing functions. 


,. S * n “ oroff and troff formatters are reasonably compatible, it is usually possible to prepare input accept¬ 
able to both. Conditional input is provided that enables the user to embed input expressly destined for either 
program. The nroff formatter can prepare output directly for a variety of terminal types and is capable of uti¬ 
lizing the full resolution of each terminal. 


The troff processor is a text-formatting program for driving a phototypesetter on the UNIX operating sys¬ 
tem. It is capable of producing high quality text. The phototypesetter normally runs with four fonts containing 
Roman, italic, and bold letters; a full Greek alphabet; a substantial number of special characters; and mathe¬ 
matical symbols. Characters can be printed in a range of sizes and placed anywhere on the page. 


Full user control over fonts, sizes, and character positions, as well as the usual features of a formatter 
(right-margin justification, automatic hyphenation, page titling and numbering, etc.) are provided by the troff 

taa^ting 1 tasks Pr ° VideS maCr ° 3 ' arithmetic variables and operations, and conditional testing for complicated 

2. Usage 

The general form of invoking an nroff or troff formatter at the UNIX operating system command level 


nroff options files 
or 

troff options files 


where options represents any of a number of option arguments and files represents the list of files containing 
the document to be formatted. An argument consisting of a single minus sign (-) is taken to be a file name cor-°- 
spondmg to the standard input. Input is taken from the standard input if no file names are given. Options mav 
appear in any order so long as they appear before the files. 
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OPTION 

-o list 


-n N 
-sN 

-mname 


-cname 


-raN 

-i 

-q 

-z 

-kname 


nroff and troff 

EFFECT 

Prints only pages whose page numbers appear in list, which consists of comma-separated 
numbers and number ranges. 

• A number range has the form N-M and means pages N through Af 

• An initial -N means from the beginning to page N 

• A final N- means from page N to the end. 

Number the first generated page N. 

Stop every N page (and cause the bell control character to be output to the terminal). The 
nroff formatter will halt after every N pages (default N= 1) to allow paper loading or 
changing and will resume upon receipt of a new line. The troff formatter will stop the 
phototypesetter every N pages, produce a trailer to allow changing cassettes, and resume 
after the phototypesetter START button is pressed. 

Prepend the macro file 

/usr/lib/tm ac/t m ac .name 

to the input files. Multiple -m macro package requests on a command line are accepted 
and are processed in sequence. 

Prepend the macro files 

/usr/lib/macros/cmp.(nt].[dt].name 

and 

/usr/lib/m acros/ucmp.[nt].name 

to the input files. Multiple — c macro package requests on a command line are accepted. 
The compacted version of macro package name should be used if it exists. If not, the 
nroff/troff formatter will try the equivalent -mname option instead. This option should 
be used instead of -m because it makes the nroff/troff formatters execute significantly 
faster. 

Set register a (one character) to N. 

Read standard input after the input files are exhausted. 

Invoke the simultaneous input/output mode of the rd request. 

Suppress formatted output. Only message output will occur (from tm requests and diag¬ 
nostics). 

Produce a compacted macro package from this invocation of the nroff/troff formatter. 
This option has no effect if no .co request is used in the nroff/troff formatter input. Oth¬ 
erwise, the compacted output is produced in files d.name and t.name. 
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OPTION 


EFFECT 


nroff Only 


-Tname 


-e 


-h 


-u n 


OPTION 


Specify the name of the output terminal type. Currently defined names are: 37 (default) 
for the TELETYPE Model 37, tn300 for the GE TermiNet 300 (or any terminal without 
half-line capabilities), 300 for the DASI 300, 300s for the DASI 300s, and 450 for the 
DASI 450. 

Produce equally spaced words in adjusted lines using full terminal resolution. 

Use output tabs during horizontal spacing to speed output and to reduce output byte count. 
Device tab settings are assumed to be every eight nominal character widths. The default 
settings of logical input tabs are also every eight nominal character widths. 

Set the emboldening factor (number of character overstrikes) in the nroff formatter for 
the third font position (bold) to be n (zero if n is missing). 

troff Only 

EFFECT 


t Direct output to the standard output instead of the phototypesetter. 

Refrain from feeding paper and stopping phototypesetter at the end of the run. 

-w Wait until phototypesetter is available if busy. 

-b Report whether phototypesetter is busy or available. No text processing is done. 

-a Send a printable approximation in American Standard Code for Information Interchange 

(ASCII) character set of the results to the standard output. This approximates a display 
of the document 

Print all characters in point size N while retaining all prescribed spacings and motions to 
reduce phototypesetter elapsed time. 

— ^ Prepare output for the Murray Hill Computation Center phototypesetter and direct it to 

the standard output. 

Each option is invoked as a separate argument. For example: 
rnoff -o4,8-10 -T300s -mabc filel file2 

requests formatting of pages 4, 8, 9, and 10 of a document contained in the files named filel and file2, specifies 
the output terminal as a DASI 300s, and invokes the macro package aba 

Various preprocessors and postprocessors are available for use with the nroff and troff formatters: 

• The equation preprocessors are neqn and eqn (for nroff and troff formatters, respectively). 

• The table-construction preprocessor is tbl. 

• A reverse-line postprocessor for multiple-column nroff formatter output on terminals without reverse¬ 
line ability is col. The TELETYPE Model 37 escape sequences that the nroff formatter produces by de¬ 
fault are expected by col. 
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• The TELETYPE Model 37-simulator postprocessor for printing nroff formatter output on a Tektronix 
4014 is 4014. 

• The phototypesetter-simulator postprocessor for the troff formatter that produces an approximation 
of photo typesetter output on a Tektronix 4014 is tc. For example, in 

tbl files I eqn I troff -t (options] I tc 

the first I indicates the piping of tbl output to eqn input; the second I indicates the piping of eqn 
output to the troff formatter input; and the third I indicates the piping of the troff formatter 
output to file tc 
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3. NROFF/TROFF Reference Mongol 


3.1 General Explanation 


3.1.1 Form of Input 


ramitfr. 1 C ° n ?!? tS °. f text liae . s ’ w L hich destine d to be printed, interspersed with control lines, which set pa¬ 
rameters or otherwise control subsequent processing. Control lines begin with a control character normally a 

Z;Z e “"“‘•- foU r ed »* »• « *^»cur name that spSf.es a basie re, u e,, „r 'he snE«L 
of a user-defined macro in place of the control line. The acute accent control character suppresses the break 
fr° the forcedoutput of a P a [tially filled line) caused by certain requests. Control characters may be sepa- 

S f r^ qUeSt/maCr ° DameS wh V tC space (spaces and/or tabs > for esthetic reasons. Names must be fol- 
° n d , by T ® hl h p e 5 a ; space or a ? ewhne character. Control lines with unrecognized request/macro names are 

request is displayed Cr ° SS rCferenCe ° f reqUC3t nameS t0 the Uble in this section where an explanation of the 


Various special functions may be introduced anywhere in the input by means of an escape character (\) 
For example, the function \ni? causes the interpolation of the contents of the number register R in place of the 

i C10 T?? b p r /^ Ster R 13 Clther an Xf0T 3 3ingle letter register name or a 2-character register 

name, labie 3.B itemizes escape sequences for characters, indicators, and functions 


3.1.2 Formatter and Device Resolution 


The troff processor internally uses 432 units/inch, corresponding to the Wang Laboratories 
phototypesetter which has a horizontal resolution of 1/432 inch and a vertical resolution of 1/144 inch. It rounds 
horizontal/vertical numerical parameter input to the actual horizontal/vertical resolution of the typesetter. 


The nroff processor internally uses 240 units/inch, corresponding to the least common multiple of the hori¬ 
zontal and vertical resolutions of various typewriter-like output devices. It rounds numerical input to the actual 
resolution of the output device indicated by the -T option (default Model 37 Teletype). 


3.1.3 Numerical Parameter Input 

Both nroff and troff formatters accept numerical input with the appended scale indicators shown in the 
ollowing table, where 5is the current type size in points, Vis the current vertical line spacing in basic units 
and G is a nominal character width in basic units. 


SCALE 


NUMBER OF BASIC UNITS 

INDICATOR 

MEANING 

TROFF 

NROFF 

i 

Inch 

432 

240 

c 

Centimeter 

432x50/127 

240x50/127 

p 

Pica = 1/6 inch 

72 

240/6 

m 

em = 5 points 

6x5 

C 

n 

en = em/2 

3x5 

C, same as em 

P 

Point = 1/72 inch 

6 

240/72 

u 

Basic unit 

1 

1 

V 

none 

Vertical line space 

Default (see following text) 

V 

V 
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In nroff processors, both em and en are taken to be equal to C, which is output-device-dependent; common 
values are 1/10 and 1/12 inch. Actual character widths in the nroff formatter need not be all the aame. Con¬ 
structed characters (such as ->) are often extra wide. Default scaling is: 

• em for horitontally oriented requests (.11, .in, .ti, .ta, .It, .po, .me) and functions (\k, \1). 

• V for vertically oriented requests (.pi, .wh, .ch, .dt, .sp, .§v, ,ne, .rt) and functions (\v, \x, \L) 

• p for .vs request 

• u for .nr, if, and ie requests. 

All other requests ignore scale indicators. When a number register containing an already appropriately scaled 
number is interpolated to provide numerical input, the unit scale indicator (u) may need to be appended to pre¬ 
vent an additional inappropriate default scaling. The number, N, may be specified in decimal-fraction form but 
the parameter finally stored is rounded to an integer number of basic units. 

The absolute position indicator (I) may be prepended to a number N to generate the distance to the vertical 
or horizontal place N. 

• For vertically oriented requests and functions, \N becomes the distance in basic units from the current 
vertical place on the page or in a diversion (paragraph 3.7) to the vertical place N. 

• For all other requests and functions, Wbecomes the distance from the current horizontal placeun the 
input line to the horizontal place N. 

For example 


.sp 13.2c 

will space in the required direction to 3.2 centimeters from the top of the page. 

3.1.4 Numerical Expressions 

Wherever numerical input is expected, an expression involving parentheses, the arithmetic operators +, - 
,/,*,% (mod), and the logical operators <, >, <-, >-, - (or - *), & (and),: (or) may be used. Except where 
controlled by parentheses, evaluation of expressions is left to right; there is no operator precedence. In the case 
of certain requests, an initial + or - is stripped and interpreted as an increment or decrement indicator. In the 
presence of default scaling, the desired scale indicator must be attached to every number in an expression for 
which the desired and default scaling differ. For example, if the number register x contains 2 and the current 
point size is 10, then: 

J1 (4.25i+\nxP+3)/2u 

will set the line length to Vt the sum of 4.25 inches + 2 picas + 3 ems (30 points since the point size is 10). 

3.1.5 Notation 

Numerical parameters are indicated in this manual in two ways. A ±N means that the argument may take 
the forms N, +N, or -N and that the corresponding effect is to set the affected parameter to N, to increment 
it by N, or to decrement it by N, respectively. Plain N means that an initial algebraic sign is not an increment 
indicator but merely the sign of N. Generally, unreasonable numerical input is either ignored or truncated to 
a reasonable value. For example, most requests expect to set parameters to non-negative values; exceptions are 
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•sp, .wh, .ch, Jir, and .if. The requests .ps, Jt ,. 
in the absence of an argument. 


po, .vs, .Is, .11, an, and .It restore the previous parameter value 


• j-character arguments are indicated by single lowercase letters and 1- or 2-character arguments are 
indicated by a pair of lowercase letters. Character string arguments are indicated by multicharactw mnemon- 


3.2 Font and Character Size Control 


3.2,1 Fonts 


n D n ef l Ultm ?1 nted f ° ntS are Times Roman (R), Times Italic (I), Times Bold (B), and Special Mathematical 
( ) on physical typesetter positions 1, 2, 3, and 4, respectively. These font styles are shown in Fig. 3.1. The cur- 
rent font, initially Times Roman, may be changed (among the mounted fonts) by use of the .ft request or bv 
imbedding at any desired point either \fx, \f(xx, or \tN where * and x* are the name of a mounted font and 
IVis a numerical font position. It is not necessary to change to the Special Font; characters on that font are auto¬ 
matically handled. A request for a named but not mounted font is ignored. 


The troff processor can be informed that any particular font is mounted by use of the .fp request. The list 
of known fonts is installation dependent. In the subsequent discussion of font-related requests, ^represents 
either a 1- or 2-character font name or the numerical font position, 1 through 4. The current font is available 
as numerical position in the read-only number register Jt. 

Font control is understood by the nroff formatter which normally underlines italic characters. Table 3.C 
is a summary and explanation of font control requests. 


3.2.2 Character Set 


The troff character set consists of the so-called Commercial II character set plus a Special Mathematical 
font character set each having 102 characters. All ASCII characters are included with some on the Special Math¬ 
ematical font The ASCII characters are input as themselves (with three exceptions); and non-ASCII characters 
are input in the form \(xx, where xxis a 2-character name given in Table 3.D. The three ASCII character excep- 
tions are mapped as follows: 


ASCII INPUT 

PRINTED BY TROFF 

CHARACTER 

NAME 

CHARACTER 

NAME 

t 

acute accent 

t 

close quote 

< 

grave accent 

« 

open quote 

— 

minus 

- 

hyphen 


The characters ', \ and - may be input by V, V , and \- respectively, or by their names. The ASCII characters 

®’ "' * • and — exist on the Special Mathematical font and are printed as a one em space 

if that font is not mounted. 

The nroff processor understands the entire troff character set but can print only: 

• ASCII characters 

• Additional characters as may be available on the output device K 
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• Such characters as may be able to be constructed by overstriking or other combinations 

• Those characters that can reasonably be mapped into other printable characters. 

The exact behavior is determined by a driving table prepared for each device. The characters ', and _ print 

as themselves. 

3.2.3 Character Size 

Character point sizes available are 6, 7, 8, 9,10, 11,12,14,16, 18, 20, 22, 24, 28, and 36. This is a range of 
1/12 inch to 1/2 inch. The .ps request is used to change or restore the point size. Alternatively, the point size 
may be changed between any two characters by imbedding a \sN at the desired point to set the size Xx> N or 
a \s±N(\ < N< 9) to increment/decrement the size by N, \sO restores the previous size. Requested point size 
values that are between two valid sizes yield the larger of the two. The current size is available in the .s number 
register. The nroff formatter ignores type size control. Table 3.E is a summary and explanation of character 
size requests. 

3.3 Page Control 

Top and bottom margins are not automatically provided. They may be defined by two macros which set traps 
at vertical positions 0 (top) and —N(Ntrom the bottom). A pseudo-page transition onto the first page occurs 
either when the first break occurs or when the first nondiverted text processing occurs. Arrangements for a 
trap to occur at the top of the first page must be completed before this transition. A summary and explanation 
of page control requests is shown in Table 3.F. References to the current diversion mean that the mechanism 
being described works during both ordinary and diverted output (the former is considered as the top diversion 
level). 

Usable page width on the phototypesetter is about 7.54 inches. The left margin begins about 1/27 inch from 
the edge of the 8-inch wide, continuous roll paper. Physical limitations on the nroff processor output are output- 
device-dependent 

3.4 Text Filling, Adjusting, and Centering 
3.4.1 Riling and Adjusting 

Normally, words are collected from input text lines and assembled into an output text line until some word 
does not fit An attempt may be made to hyphenate the word in an effort to assemble a part of it into the output 
line. The spaces between the words on the output line are increased to spread out the line to the current line 
length minus any current indent. A word is any string of characters delimited by the space character or the 
beginning/end of the input line. Any adjacent pair of words that must be kept together (neither split across 
output lines nor spread apart in the adjustment process) can be tied together by separating them with the 
unpaddable space backslash-space character (\). The adjusted word spacings are uniform in the troff 
formatter, and the minimum interword spacing can be controlled with the .ss request. In the nroff formatter, 
they are normally nonuniform because of quantization to character-size spaces; however, the command line op¬ 
tion -e causes uniform spacing with full output device resolution. Filling, adjustment, and hyphenation can 
all be prevented or controlled. The text length on the last line output is available in the .n number register, and 
text base-line position on the page for this line is in the nl number register. The text base-line high-water mark 
(lowest place) on the current page is in the Ji register. 

An input text line ending with n ?, or ! is taken to be the end of a sentence, and an additional space character 
is automatically provided during filling. Multiple interword space characters found in the input are retained, 
except for trailing spaces; initial spaces also cause a break. 

When filling is in effect, a \p escape sequence may be imbedded in or attached to a word to cause a break 
at the end of the word and have the resulting output line spread out to fill the current line length. 
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A. text input line that happens to begin with a control character can be made not to look like a control line 
by prefacing it with the nonprinting, zero-width filler character (\&). Another way is to specify output transla¬ 
tion of some convenient character into the control character using the .tr request. 

3.4.2 Interrupted Text 


Copying of an input line in no-fill mode can be interrupted by terminating the partial line with a \c escape 
sequence. The next encountered input text line will be considered to be a continuation of the same line of input 
text. Similarly, a word within filled text may be interrupted by terminating the word (and line) with \c- the 
next encountered text will be taken as a continuation of the interrupted word. If the intervening control lines 
cause a break, any partial line will be forced out along with any partial word. 

Table 3.G is a summary and explanation of filling, adjusting, and centering requests. 

3.5 Vertical Spacing 


3.5.1 Baseline Spacing 

Vertical spacing size (V) between base lines of successive output lines can be set using the .vs request with 
a resolution of 1/144 inch - Vz point in the troff formatter and to the output device resolution in the nroff 
formatter. Spacing size must be large enough to accommodate character sizes on affected output lines. For the 
common type sizes (9 through 12 points), usual typesetting practice is to set V to two points greater than the 
point size; troff default is 10-point type on a 12-point spacing. The current V is available in the .v register. 
Multiple- V line separation (e.g., double spacing) may be obtained with a .Is request. 

3.5.2 Extra Una Space 


If a word contains a vertically tall construct requiring the output line containing it to have extra vertical 
space before and/or after it, the extra line space function \x’N’ can be imbedded in or attached to that word. 
In this and other functions having a pair of delimiters around their parameter, the delimiter choice is arbitrary 
except that it can not look like the continuation of a number expression for N. 


• If JVis negative, the output line cdntaining the word will be preceded by AT extra vertical spaces. 

• If Nis positive, the output line containing the word will be followed by N extra vertical spaces. 

• If successive requests for extra space apply to the same line, the maximum values are used. 

The most recently utilized post-line extra line space is available in the .a register. 

3.5.3 Blocks of Vertical Space 

A block of vertical space is ordinarily requested using .sp, which honors the no-space mode and which does 
not space past a trap. A contiguous block of vertical space may be reserved using the .sv request. 

Table 3.H is a summary and explanation of vertical spacing requests. 

3.6 Line Length and Indenting 

The maximum line length for fill mode may be set with a .11 request. The indent may be set with a .in re¬ 
quest, an indent applicable to only the next output line may be set with the .ti request. The line length includes 
indent space but not page offset space. The line length minus the indent is the basis for centering with the .ce 
request. If a partially collected line exists, the effect of .11, .in, or .ti is delayed until after that line is output. 
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In fill mode, the length of text on an output line is less than or equal to the line length minus the indent. The 
current line length and indent are available in registers .1 and .i, respectively. The length of 3-part titles pro¬ 
duced by .tl is independently set by .It. Table 3.1 is a summary and explanation of line length and indenting re¬ 
quests. 

3.7 Macros, Strings, Diversions, and Position Traps 

3.7.1 Macros and Strings 

A macro is a named set of arbitrary lines that may be invoked by name or with a trap. A string is a named 
string of characters, not including a newline character, that may be interpolated by name at any point. Request, 
macro, and string names share the same name list. Macro and string names may be 1- or 2-characters long and 
may usurp previously defined request, macro, or string names. Any of these entities may be renamed with .rn 
or removed with ,rm. 

o Macros are created by .de and .di and appended by .am and .da (.di and .da cause normal output to 
be stored in a macro) 

o Strings are created by .ds and appended by .as. 

A macro is invoked in the same way as a request; a control line beginning .xx will interpolate the contents of 
macro xx. The remainder of the line may contain up to nine arguments. The strings x and xx are interpolated 
at any desired point with \*xand \*(xx, respectively. String references and macro invocations may be nested. 

3.7.2 Copy Mode Input Interpretation 

During the definition and extension of strings and macros (not by diversion), the input is read in copy mode. • 
The input is copied without interpretation except that 

o Contents of number registers indicated by \n are interpolated. 

e Strings indicated by \* are interpolated. 

o Arguments indicated by \$ are interpolated. 

o Concealed newline characters indicated by \<newline> are eliminated, 
o Comments indicated by \ " are eliminated. 

o \t and \a are interpreted as ASCII horizontal tab and start of heading (SOH), respectively (Part 9). 
o \\ is interpreted as “\”. 
o \. is interpreted as 

These interpretations can be suppressed by prepending a \. For example, since \\ maps into a \, \\n will copy 
as \n which will be interpreted as a number register indicator when the macro or string is reread. 

3.7.3 Argument* 

When a macro is invoked by name, the remainder of the line may contain up to nine arguments. The argu¬ 
ment separator is the space character, and arguments may be surrounded by double-quotes to permit imbedded 
space characters. Pairs of double-quotes may be imbedded in double-quoted arguments to represent a single 
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* rgUm '” 15 ° n m “ a * “"““W «•*» «ta«-r may be (lied t« ton- 

>J!?fji and “? T?“ avaiUbU “ tb *i- 

F^tSESSS 

.de xx \" begin definition 
Today is \\$1 the \\$2. 

, „ , - \" end definition 

and called by 

jcx Monday 14th 
to produce the text 

Today is Monday the 14th. 

ta !te ln ' i ' * Uh * Prepe " ded V ®* ""“I*- of oorrently available argianeme 1, 

la (n0nmacro) level in .hi. implemen^tion. Becanae ..ring referencing 

are .Xb^itU“ tojtoo*" aVaUable from ’ ixUa a N ° 

Arguments are copied in copy mode onto a stack where they are available for referent n,» - 

3.7.4 Diversions 

hnri^^ 

;t;:^bofd:nid e rb h d? f ± s? .4 r T d 

iff.it It b ^*- d ‘^ d text that 18 * verted can be reread correctly only if these modes are aeain or still in 
effect at reread time One way to do this is to imbed in the diversionthe appropriatex» orl2K!L?2£ 
the transparent mechanism described in paragraph 3.10.6. appropriate .cs or .bd request with 

. vo P/. V , er3 . 10ns ma y b « n ? sted and certain parameters and registers are associated with the current diversion 
(the top non-diversion level may be thought of as diversion level 0). These parameters and registers are: 

• diversion trap and associated macro 

• no-space mode 

• internally saved marked place (see ,mk and .rt) 

• current vertical place (.d register) 

• current high-water text base line (.h register) 
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• current diversion name (.2 register). 

3.7.5 Trop* 

Three types of trap mechanisms are available: 

• page trap 

• diversion trap 

• input-line-count trap. 

Macro-invocation traps may be planted using .wh requests at any page position including the top. This trap 
position may be changed using .ch. Trap positions at or below the bottom of the page have no effect unless or 
until moved to within the page or rendered effective by an increase in page length. Two traps may be planted 
at the same position only by first planting them at different positions and then moving one of the traps; the 
first planted trap will conceal the second unless and until the first one is moved. If the first planted trap is 
moved back, it again conceals the second trap. The macro associated with a page trap is automatically invoked 
when a line of text is output whose vertical size reaches or sweeps past the trap position. Reaching the bottom 
of a page springs the top-of-page trap, if any, provided there is a next page. The distance to the next trap position 
is available in the .t register; if there are no traps between the current position and the bottom of the page, the 
distance returned is the distance to the page bottom. 

Macro-invocation traps, effective in the current diversion, may be planted using .dt requests. The .t register 
works in a diversion. If there is no subsequent trap, a large distance is returned. 

Table 3J is a summary and explanation of macros, strings, diversion, and position traps requests. 

3.8 Number Registers 

A variety of predefined number registers (Table 3.K) are available to the user. In addition, the user may 
define his own named registers. Register names are 1- or 2-characters long and do not conflict with request, 
macro, or string names. Except for certain predefined read-only number registers (Table 3.L), a number register 
can be read, written, automatically incremented or decremented, and interpolated into the input in a variety 
of formats. One common use of user-defined registers is to automatically number sections, paragraphs, lines, 
etc. A number register may be used any time numerical input is expected or desired and may be used in numeri¬ 
cal expressions. 

Number registers are created and modified using the .nr request, which specifies name, numerical value, 
and automatic increment size. Registers are also modified if accessed with an automatic incrementing sequence. 
If the registers xand xxboth contain N and have the automatic increment size M, the following access sequences 
have the effect shown as follows: 


SEQUENCE 

EFFECT ON 

REGISTER 

VALUE 

INTERPOLATED 

nx 

none 

N 

n(xx 

none 

N 

n+x 

x incremented by M 

N+M 

n-x 

x decremented by M 

N-M 

n+(xx 

xx incremented by M 

N+M 

n-(xx 

xx decremented by M 

N-M 
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t0 . Accordln S t0 the format specified by the .af request, a number register is converted (when interpolated) 


• decimal (default) 

• decimal with leading zeros 

• lowercase Roman 

• uppercase Roman 


• lowercase sequential alphabetic 


• uppercase sequential alphabetic. 

Table 3.M is a summary and explanation of number registers requests. 

3.9 Tabs, Leaders, and Fields 


3.9.1 Tabs and Leaders 

The ASCII horizontal tab character and the ASCII SOH character (the leader) can both be used to generate 
either horizontal motion or a string of repeated characters. The length of the generated entity is governed by 
internal tab stops specified with a .ta request. The default difference is that tabs generate motion and leaders 
generate a string of periods; .tc and .lc offer the choice of repeated character or motion. There are three types 
of internal tab stops: left justified, right justified, and centered. In the following table- 


• next-string consists of the input characters following the tab (or leader) up to the next tab (or leader) 
or end of line 


* D ^ th ? ^stance from the current position on the input line (where a tab or leader was found) to the 
next tab stop 

• W is the width of next-string. 


TAB 

LENGTH OF MOTION OR 

LOCATION OF 

TYPE 

REPEATED CHARACTERS 

. n»xt-»tring 

Left 

D 

Following D 

Right 

D-W 

Right justified within D 

Centered 

D-W/2 

Centered on right end of D 


The length of generated motion is allowed to be negative but that of a repeated character string cannot be. 
epeated character strings contain an integer number of characters, and any residual distance is prepended 
as motion. Taos (or leaders) found after the last tab stop are ignored, but they may be used as next-stringtermi- 


Tabs and leaders are not interpreted in copy mode. The \t and \a always generate a noninterpreted tab 
and leader, respectively, and are equivalent to actual tabs and leaders in copy mode. 
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3.9.2 Fields 

A field is contained between a pair of field delimiter characters. It consists of substrings separated by pad¬ 
ding indicator characters. The field length is the distance on the input line from the position where the field 
begins to the next tab stop. The difference between the total length of all the substrings and the field length 
is incorporated as horizontal padding space that is divided among the indicated padding places. The incorpo¬ 
rated padding is allowed to be negative. For example, if the field delimiter is # and the padding indicator is 
*, then xxx~right # specifies a right-justified string with the string xxx centered in the remaining space. 

Table 3.N is a summary and explanation of tab, leader, and field requests. 

3.10 Input/Output Conventions and Character Translations 
3.10.1 Input Character Translations 

The newline character delimits input lines. In addition, STX, ETX, ENQ, ACK, and BEL are accepted and 
may be used as delimiters or translated into a graphic with a .tr request. All others are ignored. 

The escape character (\) introduces sequences that cause the following character to mean another character 
or to indicate some function. A complete list of such sequences is given in Table 3.B. The escape character: 

• should not be confused with the ASCII control character ESC of the same name 

• can be input with the sequence \\ 

• can be changed with .ec, and all that has been said about the default \ becomes true for the new escape 
character. 

A \e sequence can be used to print the current escape character. If necessary or convenient, the escape mecha¬ 
nism may be turned off with .eo and restored with .ec. A summary and explanation of input character transla¬ 
tions requests are contained in Table 3.0. 

3.10.2 Ligatures 

Five ligatures are available in the troff character set: fi, fl, ff, ffi, and ffl. They may be input (even in the nroff 
formatter) by \(fi, \(fl, \(ff, \(Fi, and \(F1, respectively. The ligature mode is normally on in the troff 
formatter and automatically invokes ligatures during input. A summary and explanation of ligature requests 
are included in Table 3.0. 

3.10.3 Backspacing, Underlining, and OverStriking 

Unless in copy mode, the ASCII backspace character is replaced by a backward horizontal motion having 
the width of the space character. Underlining as a form of line drawing and, as a generalized overstriking func¬ 
tion, is described in Part 12. 

The nroff processor underlines characters automatically in the underline font, specifically with the .uf re¬ 
quest. The underline font is normally on font position 2 (Times Italic). In addition to .ft request and \fF escape 
sequence, the underline font may be selected by .ul and .cu requests. Underlining is restricted to an output- 
device-dependent subset of reasonable characters. A summary and explanation of backspacing, underlining, and 
overstriking requests are included in Table 3.0. 

3.10.4 Control Characters 

Both the break control character (.) and the ( no-break ) control character ’ may be changed, if desired. Such 
a change must be compatible with the design of any macros used in the span of the change and particularly of 
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any .^ P ^ VOked maCr0S - A summar y and explanation of the .cc and .c2 control character requests are included 
in I able 3.0. 

3.10.5 Output Translation 

One character can be made a stand-in for another character using the .tr request. All text processing (e.g. 
character comparisons) takes place with the input (stand-in) character which appears to have the width of the 
final character. Graphic translation occurs at the moment of output (including diversion). Included in Tabie 3 0 
is a summary and explanation of the output translation request. 

3.10.6 Transparent Throughput 

An input line beginning with a \! is read in copy mode and transparently output (without the initial \!); 
the text processor is otherwise unaware of the line’s presence. This mechanism may be used to pass control in¬ 
formation to a post-processor or to imbed control lines in a macro created by a diversion. 

3.10.7 Commonts and Concealed Newline Characters 

An uncomfortably long input line that must stay one line (e.g., a string definition or no-filled text) can be 
split into many physical lines by ending all but the last one with the escape \. The sequence \<newline> is ig¬ 
nored except in a comment. Comments may be imbedded at the end of any line by prefacing them with \ ”. 
The newline character at the end of a comment cannot be concealed. A line beginning with \ ” will appear as 
a blank line and behave like .sp 1; a comment can be on a line by itself by beginning the line with .\ " 

3.11 Local Horizontal/Vertical Motion and Width Function 

3.11.1 Local Motion 

The functions \y*N’ and \h.’N* can be used for local vertical and horizontal motion, respectively. The dis¬ 
tance N may be negative; the positive directions are rightward and downward A local motion is one contained 
within a line. To avoid unexpected vertical dislocations, it is necessary that the net vertical local motion (within 
a word in filled text and otherwise within a line) balance to zero. The above and certain other escape sequence* 
providing local motion are summarized and explained in Table 3.P. As an example, E* is generated by the se¬ 
quence E\v’-0.5’\s-4\&2\s0\v , 0.5’ 

3.11.2 Width Function 

The width function \w'string’ generates the numerical width of string (in basic units). Size and font 
changes may be imbedded in string and will not affect the current environment. For example, .ti—\w’l.’u could 
be used to temporarily indent leftward a distance equal to the size of the string “1.”. 

The width function also sets three number registers. The registers st and sb are set respectively to the 
highest and lowest extent of string relative to the baseline; then, for example, the total height of the string is 
\n(stu-\n(sbu. In the troff formatter, the number register ct is set to a value between 0 and 3: 

• 0 means that all characters in string are short lowercase characters without descenders (like e) 

• 1 means that at least one character has a descender (like y) 

• 2 means that at least one character is tall (like H) 

• 3 means that both tall characters and characters with descenders are present. 
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3.11.3 Mork Horixontal Plact 

The escape sequence \kxwill cause the current horizontal position in the input line to be stored in register 
x As an example, the construction \kx wortf\b’!\nxu+2u’word will embolden word by backing up almost to 
its beginning and overprinting it, resulting in word. 

3.12 Ovorstrike, Zero-Width, Brocket, and Une Drawing Function* 

3.12.1 Ovarstrikt 

Automatically centered overstriking of up to nine characters is provided by the overstrike function 
\o 'string*. 

Characters in string are overprinted with centers aligned; the total width is that of the widest character. The 
string should not contain local vertical motion. As examples, \o’e\” produces e, and \o'>/’ produces *. 

3.12.2 Zoro-Width Characters 

The function \zcwill output c without spacing over it and can be used to produce left-aligned overstruck 
combinations. As examples, \z\(ci\(pl will produce ©, and \(br\z\(rn\(ul\(br will produce the smallest 
possible constructed box. 

3.12.3 Large Brackets 

The Special Mathematical Font contains a number of bracket construction pieces that can be combined into 
various bracket styles. The function \b 'string may be used to pile up vertically the characters in string (the 
first character on top and the last at the bottom); the characters are vertically separated by one em and the 
total pile is centered one-half em above the current base line (one-half line in the nroff formatter). For example: 


\b , \(lc\(lfE^b\(rc\(rf\x’-0.5m’\x’0.5m’ 


produces: 



3.12.4 Line Drawing 

The function \l’Nc’ will draw a string of repeated c’s toward the right for a distance N (1 is lowercase 

L). 

• If c looks like a continuation of an expression for N, it may be insulated from N with a \&. 

• If c is not specified, the base-line rule (_) is used (underline character in nroff). 

• If JVis negative, a backward horizontal motion of size N is made before drawing the string. 

Any space resulting from N/( size of c) having a remainder is put at the beginning (left end) of the string. In 
the case of characters that are designed to be connected, such as base-line rule (_), underrule (\(ul), and root 
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en (\(ru), the remainder space is covered by overlapping. If AT is less than the width of c, a single cis centered 
on a distance N. As an example, a macro to underscore a string can be written 

.de us 

\\$l\nO\(ul’ 


or one to draw a box around a string: 

.de bx 

\(br^\$l\l\(br\nO\(rnM’IO\(ul’ 


such that 


and 


yield 


and 


.us “underlined words” 


.bx “words in a box" 


underlined words 


words in a box 


The function \L’Nc’ will draw a vertical line consisting of the optional character c stacked vertically apart 
one em (one line in nroff), with the first two characters overlapped, if necessary, to form a continuous line. The 
default character is box rule (\(br); the other suitable character is bold vertical (\(bv). The line is begun with¬ 
out any initial motion relative to the current base line. A positive N specifies a line drawn downward, and a 
negative N specifies a line drawn upward. After the line is drawn, no compensating motions are made; the in¬ 
stantaneous base line is at the end of the line. 

The horizontal and vertical line drawing functions may be used in combination to produce large boxes. The 
zero-width box-rule and the one-half em wide underrule were designed to form corners when using one em verti¬ 
cal spacings. For example, the macro 

.de eb 

.sp -1 \ ” compensate for next automatic base-line spacing 

.nf \ " avoid possibly overflowing word buffer 
\h’-.5n’\L’!\\nau—r\r\\n(.lu+ln\(ur\L’-l\\nau+r\r!0u-.5n\ 

\(ul’ \ " draw box 

.fi 
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will draw a box around some text whose beginning vertical place was saved in number register a (e.g., using 
.mk a). 

3.13 Hyphenation 

The automatic hyphenation may be switched off and on. When switched on with .hy, several variants may 
be set A hyphenation indicator character may be imbedded in a word to specify desired hyphenation points or 
may be prepended to suppress hyphenation. In addition, the user may specify a small exception word list. The 
default condition of hyphenation is off. 

Only words that consist of a central alphabetic string surrounded by nonalphabetic strings (usually null) 
are considered candidates for automatic hyphenation. Words that were input containing hyphens (minus), em- 
dashes (\(em), or hyphenation indicator characters (such as mother-in-law) are always subject to splitting 
after those characters whether or not automatic hyphenation is on or off. Table 3.Q is a summary and explana¬ 
tion of hyphenation requests. 

3.14 Three-Part Title* 

The titling function .tl provides for automatic placement of three fields at the left, center, and right of a 
line with a title length specifiable with Jt. The .tl may be used anywhere and is independent of the normal text 
collecting process. A common use is in header and footer macros. Table 3.R is a summary and explanation of 
3-part title requests. 

3.15 Output Line Numbering 

Automatic sequence numbering of output lines may be requested with .nm. When in effect, a 3-digit, Arabic 
number plus a digit-space is prepended to output text lines. Text lines are offset by four digit-spaces and other¬ 
wise retain their line length. A reduction in line length may be desired to keep the right margin aligned with 
an earlier margin. Blank lines, other vertical spaces, and lines generated by .tl are not numbered. Numbering 
can be temporarily suspended with Jin or with a .nm followed by a later Jim +0. In addition, a line number 
indent I and the number-text separation S may be specified in digit-spaces. Further, it can be specified that 
only those line numbers that are multiples of some number M are to be printed (the others will appear as blank 
number fields). Table 3.S is a summary and explanation of output line numbering requests. 

Figure 32 is an example of output line numbering. Paragraph portions are numbered with M= 3: 

• jim 1 3 was placed at the beginning; 

• Jim +0 was placed in front of the second paragraph; 

• and Jim was placed at the end. 

Line lengths were also changed (by \w’0000’u) to keep the right side aligned. Another example is Jim +5 5 
x 3, which turns on numbering with the line number of the next line to be five greater than the last numbered 
line, with M= 5, spacing S untouched, and the indent I set to 3. 

3.16 Conditional Acceptance of Input 

In Table 3.T, which is a summary and explanation of conditional acceptance requests: 
e c is a 1-character, built-in condition name. 

• ! signifies not 

e N is a numerical expression. 
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• stringl and strings are strings delimited by any nonblank, nonnumeric character not in the strings. 

• snything represents what is conditionally accepted. 

Built-in condition names are: 


CONDITION 


NAMI 

TRUE IF 

0 

Current page number is odd 

e 

Current page number is even 

t 

Formatter is troff 

n 

Formatter is nroff 


fhSaSke^ greater than zero, or if strings compare identically (including motions and 

sonthlL™! X U1 , ythla ? la accepted as input. If a! precedes the condition, number, or string compari¬ 
son, the sense of the acceptance is reversed. F 

A “ y . sp f c ® 9 between the condition and the beginning of anything are skipped over. The anything can be ei- 

m ,fc??lL mPU U ine i S ,™ a ? r0 ’ 0r whatever ) or » number of input lines. In the multiline caw, the first 
line must begin with a left delimiter \{ and the last line must end with a right delimiter \}. 

J ® (if *® ls ® ) *!f identic al to .if except that the acceptance state is remembered. A subsequent and 
matching .el (else) request then uses the reverse sense of that state. The .ie-.el pairs may be nestedFor exam- 


•if e .tl ’ Even Page % 

outputs a title if the page number is even, and 


Je\n%>l\{\ 

’sp 0.5i 
.ti ’Page 
'sp0.-2i\} 

•el ,sp2.5i 

treats page 1 differently from other pages. 


3.17 Environment Switching 

. awi^h^K °[ paramet ® rs * hat control text processing are gathered together into an environment, which can 
be switched by the user. Environment parameters are those associated with some requests. The tables at the 

WtiSfr 118 SeC ?° n I ° dlcate . m “Explanation” column those requests so affected. In addition, partially col- 
WOr ? S / re m the environment - Everything else is global; examples are page-oriented parame- 
initianleT^hTf 11 ^ param f ers ’ number registers, and macro and string definitions. All environments are 
request ^ ^ dft parameter values - Table 3U1S a summary and explanation of the environment switching 


3.18 Insertions From Standard Input 

npw ?® ir T * SWitChed te f mp0 J rar l ly t0 the s y stem standard input With .rd and switched back when two 
newline characters m a row are found (the extra blank line is not used). This mechanism is intended for inser- 

board V pi^* orTfile 6 d ° Cumentatlon ' 0n the U^X operating system, the standard input can be the user key- 
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If insertions are to be taken from the terminal keyboard while output is being printed « 
command line option -q will turn off the echoing of keyboard input and prompt only with BEL. The regu 
input and insertion input cannot simultaneously come from the standard input. As an example, multiple copies 
o" P aLrmlettermay be prepared by entering insertions for all copies in one file to be used as the standard input 
and cauTi^e file con?ain P ing the letter to reinvoke itself by using the .nx request. The process would be ended 
by a .ex request in the insertion file. 

Table 3.V is a summary and explanation of insertions from the standard input requests. 

3.19 Input/Output File Switching 

Table 3.W is a summary and explanation of input/output file switching requests. 

3.20 Miscellaneous 

Table 3.X is a summary and explanation of miscellaneous requests. 

3.21 Output and Error Messages 

Output from .tm, .pm, and prompt from .rd, as well as various error messages are written onto the UNIX 
operating system standard message output The latter is different from the standard output, when compared 
to the nroff formatted output By default, both are written onto the user’s terminal, but they can be indepen¬ 
dently redirected. 

Various error conditions may occur during the operation of the nroff -and troff formatters. Certain less 
serious errors having only local impact do not cause processing to terminate. Two examples are. 

• word overflow -caused by a word that is too large to fit into the word buffer (in fill mode) 

• line overflow -caused by an output line that grew too large to fit in the line buffer. 

In both cases, a message is printed, the offending excess is discarded, and the affected word or line is marked 
at the point of truncation with a * (in nroff) or a cright hand> (in troff). The philosophy is to continue process¬ 
ing if possible, on the grounds that output useful for debugging may be produced. If a serious error occurs, pro¬ 
cessing terminates, and an appropriate message is printed. Examples are the ^ability to create, read, or wri 
files, and the exceeding of certain internal limits that make future output unlikely to be useful. 

Table 3.Y is a summary and explanation of output and error messages requests. 

3.22 Compacted Macro* 

The time required to read a macro package by the nroff formatter may be lessened by using a compacted 
macro (a preprocessed version of a macro package). The compacted version is equivalent to the noncompacted 
version, except that a compacted macro package cannot be read by the .so request. A compacted version of a 
macro package, called name, is used by the -cnamecommand line option, while the uncompacted version is used 
by the -mname option. Because -cname defaults to -mnameif the name macro package has not been compact¬ 
ed, the user should always use -c rather than -m. 

3.22.1 Building a Compacted Macro Package 

Only macro, string, and diversion definitions; number register definitions and values; environment settings; 
and trap settings can be compacted. End macro (em) requests and any commands that may interact during 
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JjSjf! p t l?ri Uti ° n K With * C / 0 mma u d ' 1 i n e 8 ettin K 8 (such a* references in the MM macro package to the number 

— 1 lin,) “ not “ mpM,ibie - Th ' r *«•« -5f-- ks: 


Separate compactible from noncompactible parts 


»£to «» *“ The .CO request Sndi- 


- — - — — v* muviv ^O^fwOgC W 1 til a ,CQ 1 

cates to the nroff formatter when to compact its current internal state. 
Compactible Material 


.co 

Noncompactible Material 


3.22.2 Produce Compacted Filet 

unt^! n -v mP ; Ctib . le ^ n s < J J n °u COmpaCtib l? 8egments have t>^n established, the nroff formatter may be run 
_k optlon . t0 bu * ld tbe compacted files. For example, if the output file to be produced is called mac 

the following may be used to build the compacted files: mac 

nroff -kmac mac 

This command causes the nroff formatter to create two files in the current directory, d.mac and tmac The 
macro file must contain a .co request Only lines before the .co request will be compacted. Both -k and jco are 

necessary. If no .co is found in the file, the -k is ignored. Likewise, if no -k appears on the command line, the 
•Co is ignored. 


M macro package must be compacted separately by the nroff formatter. Compacted macro packages de- 

h* nuJ! a 1C u ** version n f 0 ^ formatter that produced them. Any compacted macro packages must 

wJn^nSu! wh !v, a new , vers f on °l “ “ roff formatter is installed. If it is discovered that a macropackage 
was produced by a different version than that attempting to read it, the -c will be abandoned, and the equiva- 
lent —m option attempted instead. 

3.22.3 Install Compacted Files 

«nt), T M, e » t r^ COmPaCted f il e f: d ?, acand tmac> must be installed in the system macro library (/usr/lib/macres) 
with the proper names. If the files were produced by an nroff formatter, cmp.n. must be prepended to their 

stalled by r CXamp ®’ lf 1116 macro package is 03116(1 mac > the two nroff formatter compacted files may be in- 


or 


cp d.mac /usr/lib/macros/cmp.n.d.mac 
cp t.mac /usr/lib/macros/cmp.n.t.mac 


3.22.4 Install Noncompactible Segment 

The noncompactible segment from the original macro package must be installed on the system as 
/ usr/lib/ macros/ucmp. [ntj.mac 
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where n of [nt] means the nroff formatter version, and t means the troff formatter version. The 
noncompactible segment must be produced manually by using the editor. Using the mac package as an example, 
the following could be used to install the nroff formatter noncompactible segment 

$ ed mac 

/''\.co$/+,$w /usr/lib/macros/ucmp.n.mac 

4. TROFF Tutorial 
4.1 Overview 

An important rule of using the troff formatter is to use it through an intermediary. In many ways the troff 
formatter resembles an assembly language, remarkably powerful and flexible, but nonetheless such that many 
operations must be specified at a level of detail and in a form that is too difficult for most people to use effective¬ 
ly. 

There are programs that provide an interface to the troff formatter for the majority of users for two special 
applications. 

• The eqn program provides an easy to learn language for typesetting mathematics. The user does not 
need to know the troff formatter to typeset mathematics. 

• The tbl program provides the same convenience for producing tables of arbitrary complexity. 

For producing text that may contain mathematics or tables, there are a number of macro packages that 
define formatting rules and operations for specific styles of documents and reduce the amount of direct contact 
with the troff formatter. In particular, the Memorandum Macros (MM) package provides most of the facilities 
needed for a wide range of document preparation. There are also packages for viewgraphs and other special ap¬ 
plications. These packages are easier to use than the troff formatter once the user gets beyond the most trivial 
operations. They should be considered first 

In the few cases where existing packages do not accomplish the job, the solution is not to write an entirely 
new set of troff instructions from scratch but to make small changes to adapt packages that already exist. In 
accordance with this philosophy, the partof the troff formatter described here is only a small part of the whole, 
although it tries to concentrate on the more useful parts. The emphasis is on doing simple things and making 
incremental changes to what already exists. The troff formatter described is the C language version running 
on the UNIX operating system at Murray Hill. 

To use the troff formatter, the actual text must be prepared plus some information that describes how it 
is to be printed. Text and formatting information are intimately intertwined. Most commands to the troff 
formatter are placed on a line separate from the text itself, one command per line beginning with a period. For 
example 

Some text 

.ps 14 

Some more text 

will change the point size of the letters being printed to 14 point (one point is 1/72 of an inch). 

Occasionally, something special occurs in the middle of a line, such as an exponent. The formula for the area 
of a circle is typed as follows: 

Area = \( * p\fIr\fR\f\s8\u2\d\sO 

The backslash character (\) is used to introduce troff commands and special characters within a line of text. 
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4.2 Point Six** and Uno Spacing 


JJ,V2L r * q ?* 8t 1 P u‘u- r™ ‘ nce one point 18 1/72 lnch> 6 -PO‘nt characters are 1/12 inch high, and 
tt'JS ^V 8ct ?" . are * lnch hl * h - Th« re we 15 point sizes-6, 7,8. 9,10,11,12,14,16,18, 20, 22,24, 28, and 
36 point Point sue is rounded up to the next valid value, with a maximum of 36, if the number following the 
.ps request is not a legal value. 8 



Relative size changes are also legal and useful: 

\s-2UNCLE\s+2 

temporarily decreases the size by two points, then restores it. Relative size changes have the advantage that 
the sue difference is independent of the starting size of the document. The amount of the relative change is re¬ 
stricted to a single digit 8 


Another parameter that determines what the type looks like is the spacing between lines. It is set indepen¬ 
dently of the point size. Vertical spacing is measured from the bottom of one line to the bottom of the next The 
command to control vertical spacing is .vs. For running text it is usually best to set the vertical spacing about 
20 percent larger than the character size. For example, a usable combination would be 

.ps 9 
.vs lip 


Vertical spacing is partly a matter of taste, depending on how much text is to be squeezed into a given space 
and partly a matter of traditional printing style. By default, the troff formatter uses a point size of 10 and a 
vertical spacing of 12. When .vs is used without arguments, vertical spacing reverts to the previous value. 

The request is used to get extra vertical space. Used alone, it gives one extra blank line (whatever .vs 
is set). Since that may be more or less than desired, .sp can be followed by information about how much space 
is wanted. For instance: 

.sp 1.51 means “a space of 1.5 inches” (most troff processor installations understand decimal frac¬ 

tions) 

•sp 2i means “two inches of vertical space” 

• S P 2p means “two points of vertical space” 

.sp 2 or .sp 2v means “two vertical spaces" (two of whatever .vs is set). 

These same scale factors can be used after the .vs request to define line spacing. Scale factors can be used after 
most commands that deal with physical dimensions. 

All size numbers are converted internally to machine units, which are 1/432 inch (1/6 point). For most pur¬ 
poses, this is enough resolution to provide good accuracy of representation. The situation is not quite so good 
vertically, where resolution is 1/144 inch (Vi point). 
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4.3 Fonts and Spocial Characters 

The troff processor and the typesetter allow four different fonts at one time. Normally, three fonts (Times 
Roman, Times Italic, and Times Bold) and one collection of special characters are permanently mounted. The 
Greek, mathematical symbols, and miscellany of the special font are listed in Table 3.D. 

The troff processor prints in Roman unless otherwise commanded. To change the font, the .ft request is 
used: 


it B switch to bold font 
it I switch to italics font 
it R switch to Roman font, 
it P return to previous font, 

it return to previous font 

The underline request (.ul) causes the next input line to print in italics. It can be followed by a count to indi 
cate that more than one line is to be italicized. 

Fonts can also be changed within a line or word with the \f in-line sequences. For instance 


bold/ace text 


is produced by 

\fBbold\fIface\fR text 

If it is desired to do this so the previous font is left undisturbed, extra \fP sequences should be inserted: 
\fBbold\fP\fIface\fP\fR text\fP 

Since only the immediately previous font is remembered, the previous font must be restored after each change 
or it will be lost. The same is true of .ps and .vs when used without an argument 

There are other fonts available besides the standard set, although only four can be used at any given time. 
The Jj> request tells the troff formatter what fonts are actually mounted on the typesetter. For example: 

ip 3 H 

says that the Helvetica font is mounted on position 3. A list of fonts and what they look like are shown in Fig. 
3.1. Appropriate ip requests should appear at the beginning of a document if standard fonts are not used. 

It is possible to make a document relatively independent of the actual fonts used to print it by using font 
numbers instead of names. For example: \f3 and it3 mean “whatever font is mounted at position 3 . Normal 
settings are Roman font on 1, italic on 2, bold on 3, and special on 4. 

There is also a way to get synthetic bold fonts by overstriking letters with a slight offset. The .bd request 
addresses this function. 

Special characters have 4-character input names beginning with \( and may be inserted anywhere in the 
text In particular, Greek letters are all of the form \<*-, where - is an uppercase or lowercase Roman font 
letter reminiscent of the Greek. A list of these special names is given in Table 3.D. 

Some characters are automatically translated into others: grave (') and acute (')accents become open and 
close single quotation marks. Similarly, a typed minus sign becomes a hyphen. The \ input will print an ex¬ 
plicit minus sign. A \e entry causes a backslash to be printed. 
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4.4 Indents and Una lengths 

The troff processor starts with a line length of 6.5 inches, which is too wide for 8-Vi inch by 11-inch paper 
The .11 request resets the line length. For example: ' 

.11 6i 

As with the .sp request, the actual length can be specified in several ways; inches are probably the most intu¬ 
itive. The maximum line length provided by the typesetter is 7.5 inches. To use the full width, the default physi¬ 
cal left margin (page offset) must be reset. This is done by the .po request. The margin is normally slightly less 
than 1 inch from the left edge of the paper. The .po 0 request sets the offset as far to the left as it will go. 

The indent request (.in) causes the left margin to be indented by some specified amount from the page offset. 
If .injs used to move the left margin to the right and the .11 is used to move the right margin to the left, offset 
blocks of text are obtained. As an example 

.in 0.5i 
.11 -0.5i 

text to be set into a block 
.11 +0.5i 
.in —0.5i 

will create a block that looks like: 


A clergyman at Cambridge preached a sermon which one of his auditors commended. “Yes,” 
said a gentleman to whom it was mentioned, “it was a good sermon, but he stole it.” This was told 
to the preacher. He resented it, and called on the gentleman to retract what he had said. “I am 
not,” replied the aggressor, “very apt to retract my words, but in this instance I will. I said, you 
had stolen the sermon; I find I was wrong; for on returning home, and referring to the book 
whence I thought it was taken, I found it there." 


The use of + and — changes the previous setting by the specified amount rather than just overriding it. The 
distinction is quite important 

• J1 +li makes lines 1 inch longer 

• J1 li makes lines 1 inch long. 

With the an, Jl, and .po requests, the previous value is used if no argument is specified. 

The .ti request is used to temporarily indent a single line. For example, all paragraphs in this manual effec¬ 
tively begin with the .ti 3 request Since no units are specified, the line is indented three ems by default. The 
default unit for .ti, as for most horizontally oriented requests (.11, .in, .po), is ems. An em is roughly the width 
of the letter m in the current point size. Precisely, an em in size pis ppoints. Although inches are usually clearer 
than ems to people who do not set type for a living, ems have a place: they are a measure of size that is propor¬ 
tional to the current point size. The ems unit is used to make text that keeps its proportions regardless of point 
size. The ems can be specified as scale factors directly, as in .ti 2.5m. 
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Lines can be indented negatively if the indent is already positive: 

.ti -.3i 

causes the next line to be moved back 3/10 of an inch. 

To make a decorative initial capital that is three lines high: 

• The whole paragraph is indented. 

• The initial character is moved back with the .ti request. 

• The initial character is made’bigger (e.g., \s36N\sO) and moved down from its normal position (see 
Part 6). 

4.5 Tabs 

Tabs (the ASCII horizontal tab character) can be used to produce output in columns or to set the horizon¬ 
tal position of output. Typically, tabs are used only in unfilled text. Tab stops are set by default every half inch 
from the current indent but can be changed by the .ta request. Tab stops are set every inch, for example, with 
the following entry: 

.ta li 2i 3i 4i 5i 6i 

Tab stops are left justified (as on a typewriter), so lining up columns of right-justified numbers can be a 
problem. If there are many numbers or if a table layout is needed, the tbl program is available (Section 4). 

A handful of numeric columns can be done by preceding every number with enough blanks to make it line 
up when typed. For instance: 

.nf 

.ta li 2i 3i 
l tab 2 tab 3 

40tab 50tab 60 
700tab 800tab 900 
.fi 

Each leading blank is a \0 string. This is a character that does not print but has the same width as a digit. 
When printed it produces: 


1 2 3 

40 50 60 

700 800 900 
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rpni^!. 4150 . pos v ? ibl * t0 fill UP tabbed-over space with some character other than blanks by setting the tah 
replacement character with the .tc request: K iat 


•ta 1.5i 2.5i 

.tc \(ru \”(ruis_) 

Name tab Age tab 


produces 


Name. 


Age 


To reset the tab replacement character to a blank, the .tc request (with 
be drawn with the \1 escape sequence as described in paragraph 4.6.4. 


no argument) is used. Lines can alsc 


is 


The troff processor provides a general mechanism called “fields” for 
used by the tbl program. 


setting up complicated columns. This 


4.6 Local Motions 


mi The ^processor provides a number of escape sequences for placing characters of any size at any place 
They can be used to draw special characters or to tune the output for a particular appearance. Most of these 
sequences are straightforward but messy to read and tough to type correctly. 


4.6.1 Vertical Motions 

If the eqn program is not used, subscripts and superscripts are most easily done with the half-line local 
motions \u and \d sequences. To go back up the page half a point size, a \u is inserted at the desired place- 
o go down half a point size, a \d is inserted. The \u and \d should always be used in pairs. Since \u and \ 
d refer to the current point size, they should either be both inside or both outside the size changes. Otherwise 
an unbalanced vertical motion will result. 


Sometimes the space given by \u and \d is not the right amount. The \v sequence can be used to request 
an arbitrary amount of vertical motion. The in-line sequence\v> N causes motion up or down the page by the 
amount specified in N. For example, to move the character “P” down, the following would apply: 


.in +0.6i (indent paragraph) 

.11 —0.3i (shorten lines) 

.ti -0.3i (move Nback) 

\v’2\s36N\sO\v’-2’ott met Shott, Nott 
shot at Shott.... 

A minus sign causes upward motion, while no sign or a plus sign means down the page. Thus \v’-2’ causes an 
upward vertical motion of two line spaces. 


There are many other ways to specify the amount of motion 


\v’0.1i’ 
\v’3p’ 
\v’—0.5m’ 


etc. are all legal. The scale specifier i, p, or m goes inside the quotes. Any character can be used in place of th. 
quotes. This is true of all other troff formatter commands and sequences described in this section. 


Since the troff formatter does not take within-the-line vertical motions into account when figuring where 
it is on the page, output lines can have unexpected positions if the left and right ends are not at the same vertical 
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position. Thus \v, like \u and \d, should always balance upward vertical motion in a line with the same amount 
in the downward direction. 

4.6.2 Horizontal Motions 

Arbitrary horizontal motions are also available, \h is analogous to \v, except that the default scale factor 
is ems instead of line spaces. As an example, 

■ \h’-0.1i’ 

causes a backwards motion of a tenth of an inch. In a practical situation, when printing the mathematical sym¬ 
bol >, the default spacing is too wide, so eqn replaces this by 

>\h’-0.3m’> 

to produce >>. 

Frequently, \h is used with the “width function” \w to generate motions equal to the width of some charac¬ 
ter string. The construction \w’thing’ is a number equal to the width of thing in machine units (1/432 inch). 
All troff formatter computations are ultimately done in these units. To move horizontally, the width of an xfR, 
\h’ \w’xV is used. Since the default scale factor for all horizontal dimensions is m (ems), u (machine units) 
must be used, or the motion produced will be too large. Nested quotes are acceptable to the troff formatter as 
long as none are omitted. An example of this kind of construction would be to print the string .sp by overstriking 
with a slight offset The following example puts out .sp, moves left by the width of .sp, moves right one unit, 
and prints .sp again: 

.sp\h , -\w\spV\h’lu’.sp 

Part 11 describes a way of avoiding typing so much input for each command name. 

There are several special-purpose troff formatter sequences for local motion: 

• The \0 is an unpaddable (never widened or split across a line-by-line justification and filling) white 
space of the same width as a digit 

• The \ < space > is an unpaddable character the width of a space. 

• The \i is 1/6 the width of a space. 

• The V is 1/12 the width of a space. 

• The \& has zero width and is useful in entering a text line that would otherwise begin with a .. 

• The \o sequence causes up to nine characters to be overstruck, centered on the widest. This is for accents 
such as: 

syst\o" e\(ga" me t\o" e\(aa" l\o" e\(aa" phonique 
which produces 

systeme telephonique 

The accents \(ga and \(aa (V and V) are just one character to the troff formatter. 
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4.6.3 Overstrik** 


Overetnkes can be made with another special convention, \z, the zero-motion sequence. Normal horizontal 
motion is suppressed with the \zx after printing the single character x, so another character can be laid on 
top of it Although sizes can be changed within \o, characters are centered on the widest and there can be no 
horizontal or vertical motions. The \z may be the only way to get what is needed. 

A more ornate overstnke is given by the bracketing function \b, which piles up characters vertically, cen¬ 
tered on the current base line. Thus big brackets are obtained by constructing them with piled-up smaller pieces. 

4.6.4 Drawing Unas 

A convenient facility for drawing horizontal and vertical lines of arbitrary length with arbitrary characters 
is provided by the troff formatter. A 1-inch long line is printed with a \Pli’ sequence. The length can be fol¬ 
lowed by the character to use if the _ is not appropriate. The \1’0.5L’ sequence draws a ^-inch line of dots 
Escape sequence \L is analogous, except that it draws a vertical instead of a horizontal line. The document titled 
table Formatting Program describes other ways of providing horizontal and vertical lines. 

4.7 Strings 


If a paper contains a large number of occurrences of an acute accent over a letter e, typing \o " e\’" for 
each e would be a nuisance. Fortunately, the troff formatter provides a way to store an arbitrary collection 
of text in a ‘string”, and thereafter use the string name as a shorthand for its contents. Strings are one of sev¬ 
eral troff formatter mechanisms whose judicious use permits typing a document with less effort and organizing 
it so that extensive format changes can be made with few editing changes. 

A reference to a string is replaced by whatever text as defined the string. Strings are defined with the ds 
request The line 

.dse\o"e\'" 


defines the string e to have the value \o " e V " • 

String names may be either 1 or 2 characters long. They are referred to by \*x for 1-character names or 
\*(xy for 2-character names. Thus, to get 

telephone 

given the definition of the string e as above, 
t\*el\*ephone 


is the input 


If a string must begin with blanks, it is defined as 
.ds xx " text 

The double quote signals the beginning of the definition. There is no trailing quote; the end of the line terminates 
the string. 

A s ^ n 8 may be several lines long. If the troff formatter encounters a \ at the end of any line, it is thrown 
away and the next line is added to the current one. A long string can be made by ending each line except the 
last with a backslash. 
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.ds xx this \ 
is a very \ 
long string 

Strings may be defined in terms of other strings or even in terms of themselves. 

4.8 Introduction to Macros 

In its simplest form, a macro is a shorthand notation similiar to a string. For instance, if every paragraph 
is to start in exactly the same way, with a space and a temporary indent of two ems, the following requests would 
perform the operation: 


.sp 

.ti +2m 


To save typing these requests every time used, they could be collapsed into one shorthand line, such as a troff 
command, .PP. The J*P is called a macro. The way to tell the troff formatter what .PP means is to define it 
with the .de request 



.dePP 

.sp 

.ti +2m 


The first line names the macro (JPP in this example). It is in uppercase so it will not conflict with any name 
that the troff formatter might already know about The last line (_) marks the end of the definition. In between 
is the text which is inserted whenever the troff formatter sees the J*P macro call. A macro can contain any 
mixture of text and formatting requests. 


The definition of a macro has to precede its first use; undefined macros are ignored. Names are restricted 
to one or two characters. 


Using macros for commonly occurring sequences of requests is important since it saves typing and makes 
later changes easier. If it is decided that in producing a document the paragraph indent is too small, the vertical 
space is too large, and Roman font should be forced, only the definition of .PP needs to be changed to read 


.de PP \" paragraph macro 

.sp 2p 
.ti +3m 
.ft R 


The change takes effect everywhere JPP is used and is easier than changing commands throughout the whole 
document. 

A troff formatter escape sequence that causes the rest of the line to be ignored is \" • It is used to add com¬ 
ments to the macro definition (a wise idea once definitions get complicated). 

Another example of macros that start and end a block of offset, unfilled text is 


.de OS \" start indented block 

.sp 

i .nf 

.in +0.3i 
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•de OE \" end indented block 

.sp 

ii 

.in -0.3i 


The .OS and .OE macros could be used before and after text to provide the following effect* 

Copy to 
John Doe 
Richard Roberts 
Stanley Smith 

In this example, the indention used is .in +0.3i instead of .in 0.3i. This permits the nesting of the .OS and .OE 
macros to get blocks within blocks. 

Should the amount of indention be changed at a later date, it is necessary to change only the definitions 
of .OS and .OE, not individual requests throughout the whole paper. 

4.9 Titles, Pages, and Numbering 

Titles, pages, and numbering is a complicated area where nothing is done automatically. Of necessity, some 
of this section is a cookbook to be copied literally until some experience is obtained. 

To get a title at the top of each page, such as: 

left top center top right top 

it was possible on an older system (roff) to get headers and footers automatically on every page with the follow¬ 
ing: 

.he 'left top’center top’right top’ 

So ’left bottom’center bottom’right bottom’ 

This does not work in the troff formatter. Instead, specifications must be provided 

• What to do at and around the title line 

• When to print the title 

• What the actual title is. 

The .NP macro (new page) is defined to process titles at the end of one page and the beginning of the next 

.de NP 
. T>P 
’sp 0.5i 

.tl ’left top’center top’right top’ 

’sp 0.3i 


These requests are explained as follows: 

• The ’bp (begin page) command causes a skip to the top-of-page. 
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• The ’sp 0.5i command will space down to inch. 

• The .tl command prints the title. 

• The ’sp 0.31 provides another 0.3 inch space. 

The reason that the ’bp and 'sp commands are used instead of the .bp and .sp requests is that the .sp and 
.bp cause a break to take place. This means that all the input text collected but not yet printed is flushed out 
as soon as possible, and the next input line is guaranteed to start a new line of output. Had .bp been used in 
the .NP macro, a break in the middle of the current output line would occur when a new page is started. The 
effect would be to print the left-over part of that line at the top of the page, followed by the next input line on 
a new output line. This is not desired. Using ’ instead of. for a command tells the troff formatter that no break 
is to take place. The output line currently being filled should not be forced out before the space or new page. 

The list of requests that cause a break is short and natural: 

.bp .br .ce ii .nf .sp .in .ti 

Other requests cause no break, regardless of whether a. or a' is used. If a break is really needed, a .br request 
at the appropriate place will provide it 

To ask for .NP at the bottom of each page, a statement like “when the text is within an inch of the bottom 
of the page, start the processing for a new page” is used. This is done with the .wh request For example: 

.wh -li NP 

No . character is used before NP since it is simply the name of a macro and not a macro call. The minus sign 
means "measure up from the bottom of the page", so -li means 1 inch from the bottom. 

The .wh request appears in the input outside the definition of .NP. Typically, the input would be 
.de NP 

— body of macro 
"wh -li NP 

As text is actually being output the troff formatter keeps track of its vertical position on the page; and 
after a line is printed within 1 inch from the bottom, the .NP macro is activated. 

• The .wh request sets a trap at the specified place. 

• The trap is sprung when that point is passed. 

The -NP macro causes a skip to the top of the next page (that is what the ’bp was for) and prints the title with 
appropriate margins. 

Something to beware of when changing fonts or point sizes is crossing a page boundary’ in an unexpected 
font or size. Titles come out in the size and font most recently specified instead of what was intended. The length 
of a title is independent of the current line length, so titles will come out at the default length of 6.5 inches unless 
changed. Changing title length is done with the .It request. 

There are several ways to fix the problems of point sizes and fonts in titles. The .NP macro can be changed • 
to set the proper size and font for the title, and then restore the previous values, like this: 

.de NP 
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’bp 

’sp 0.5i 

.ft R \ " 

.ps 10 \ " 

.It 6i \ M 

.tl ’left'center’right' 
.ps \" 

.ft P \ - 

’sp 0.3i 


set title font to Roman 
set size to 10 point 
set length to 6 inches 

revert to previous size 
and to previous font 


™ S J erSi ° n ° f ’ NP d °fv S D * 0t if the fields in the ' tl re< 5 u «t contain size or font changes. To cope with 
that contingency requires the troff formatter “environment" mechanism discussed in Part 13. 

To get a footer at the bottom of a page, the .NP macro should be modified. One option is to have the JSTP 

vTrii 0 r "" ,eS ‘- is «° split the macro ta,o a ma^„ 

voKea at tne bottom margin) and a header macro (invoked at the top of page). 

are nrlnt^H num b?rs are computed automatically as each page is produced (starting at 1), but no numbers 

trreoue^aAhfn X v Clt 7 r® qu ® 3ted - To * et ? a S e numbers printed, the % character should be included in the 
•tl request at the position where the number is to appear. For example: 

.ti 

centers the page number inside hyphens. The page number can be set at any time with either a .bp n request 
(which immediately starts a new page numbered n) or with .pn n (which sets the page number for the next page 

tt n “ C T * ■ t0 the new !*«•)• The b P +» *«s the page number to n more than its cuient^aiue 
The .bp request without an argument means .bp +1. 

4.10 Number Registers and Arithmetic 

llM ™,® ‘ r0ff pr ° Cessor , has for doing arithmetic and defining and using variables with numeric val¬ 

ues called number registers. Number registers, like strings and macros, can be useful in setting up a document 
so it is easy to change later. They also serve for any sort of arithmetic computation. 

Like strings, number registers have 1- or 2-character names. They are set by the .nr request and are refer¬ 
enced anywhere by \nx (1-character name) or \n(xy (2-character name). 

There are quite a few predefined number registers maintained by the troff formatter, among them: 

• % for the current page number 

• nl for the current vertical position on the page 

• dy, mo, and yr for the current day, month, and year 

• .s and .f for the current size and font (the font is a number from one to four). 

with °nr. heSe in com P utations like an y oth " register, but some, like .s and .f, cannot be changed 

arp l n f; eX ^?f ° f th ® “ 3 ® ° f n “mber registers is in an older macro package where most significant parameters 

vprttfl d term ! °JL th y valu ® s ? f , a 1 handful of number registers. These include the point size for text, the 
cal spacing, and the line and title lengths. To set the point size and vertical spacing, a user may input 
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.nr PS 9 
.nr VS 11 

The paragraph macro, .PP, is roughly defined as follows: 

.de PP 
.ps \\n(PS 
.vs \\n(VSp 
itR 
.sp 0.5v 
,ti +3m 


This sets the font to Roman and the point size and line spacing to whatever values are stored in the number 
registers PS and VS. 

The reason for two backslashes is to indicate that a backslash is really meant. When the troff formatter 
originally reads the macro definition, it peels off one backslash to see what is coming next. Two backslashes 
in the definition are required to ensure that a backslash is left in the definition when the macro is used. If only 
one backslash is used, point size and vertical spacing will be frozen at the time the macro is defined, not when 
it is used. 

Protecting by an extra layer of backslashes is needed only for \n, \*. \$, arid \ itself. Things like \s, \f, 
\h, \v, etc. dp not need an extra backslash since they are converted by the troff formatter to an internal code 
immediately upon detection. 

Arithmetic expressions can appear anywhere that a number is expected. As an example: 

.nr PS \\n(PS-2 

decrements PS by 2. Expressions can use the arithmetic operators +, -, *, /, % (mod), the relational operators 
>, >=, <, <=, *, 1* (not equal), and parentheses. 

So far, the arithmetic has been straightforward; more complicated things are tricky. 

• Number registers hold only integers. In the troff formatter, arithmetic uses truncating integer division 
just like Fortran. 

• In the absence of parentheses, evaluation is done left-to-right without any operator precedence includ¬ 
ing relational operators. Thus: 

7*-4+3/13 

becomes -1. 

Number registers can occur anywhere in an expression and so can scale indicators like p, i, m, etc. (but no spac¬ 
es). Although integer division causes truncation, each number and its scale indicator is converted to machine 
units (1/432 inch) before any arithmetic is done, so li/2u evaluates to 0.5i correctly. 

The scale indicator u often has to appear when least expected, in particular when arithmetic is being done 
in a context that implies'horizontal or vertical dimensions. For example, .11 7/2i is not 3- l /2 inches. Instead, it 
is really 7 ems/2 inches. When translated into machine units, it becomes 0 (this is because the default units for 


\ H reset size 
\" spacing 
\" font 
\ " half a line 
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horizontal parameters [like .11] are ems). Another incorrect try is .11 7i/2. The 2 is 2 ems, so 7i/2 is small, al¬ 
though not 0. The .11 7i/2u must be used. A safe rule is to attach a scale indicator to every number, even con- 
stants. 


F ? r arithmetic done within a .nr request, there is no implication of horizontal or vertical dimension so the 
default units are “units”, and 7i/2 and 7i/2u mean the same thing. Thus: 


.nr 11 7i/2 
.11 \\n(llu 

accomplishes what is desired as long as the u on the .11 request is included. 


4.11 Macros With Arguments 

Two things are needed to be able to define macros that can change from one use to the next according to 
parameters supplied as arguments: 

1. When the macro is defined, it must be indicated that some parts will be provided as arguments when the 
macro is called. 

2. When the macro is called, the actual arguments to be plugged into the definition must be provided. 

An example would be to define a macro (.SM) that will print its argument two points smaller than the surround¬ 
ing text 


.deSM 

\s-2\\$l\s+2 


The macro call would appear 
.SM SMALL 

The argument SMALL in this example would then appear two points smaller than the rest of the print 

Within a macro definition, the symbol \\$n refers to the nth argument with which the macro was called. 
Thus \\$1 is the string to be placed in a smaller point size when .SM is called. 

A slightly more complicated version is the following definition of .SM which permits optional second and 
third arguments that will be printed in the normal size: 

.de SM 

\\$3\s-2\\$l\s+2\\$2 

Arguments not provided when the macro is called are treated as empty. The macro call 
.SM ABLE ), 

would appear (with ABLE in smaller type) 

ABLE), 

The macro call 

.SM BAKER ). ( 
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produces the following (with BAKER in smaller print): 

(BAKER). 

It is convenient to reverse the order of arguments because trailing punctuation is much more common than lead¬ 
ing. The number of arguments that a macro was called with is available in number register .$. 

The macro, .BD, is used to make “bold Roman” for troff formatter command names in text. It combines 
horizontal motions, width computations, and argument rearrangement: 

.de BD 

\&\\$3\fl\\$l\h’-\w\\$ru+2u\\$l\fP\\$2 

The \h and \w escape sequences need no extra backslash. The \& is there in case the argument begins with 
a period. Two backslashes are needed with the \\$n commands to protect one of them when the macro is being 
defined. A second example will make this clearer. A .SH macro can be defined to produce automatically num¬ 
bered section headings with the title in smaller size bold print. The use is 

.SH " Section title ..." 

If the argument to a macro is to contain blanks, it must be surrounded by double quotes. 

The definition of the .SH macro is 


.nr SH 0 

\ " initialize section number 

.de SH 


.sp 0.3i 


.ft B 


.nr SH \\n(SH+l 

\ " increment number 

.ps \\n(PS-l 

\ " decrease PS number 

\\n(SH. \\$1 

\ " title 

.ps \\n(PS 

\ " restore PS 

.sp 0.3i 


itR 



The section number is kept in number register SH, which is incremented each time just before use. 

Note: A number register may have the same name as a macro without conflict but a string may not. 

A \\n(SH and \\n(PS was used instead of a \n(SH and \n(PS. Had \n(SH been used, it would have 
yielded the value of the register at the time the macro was defined, not at the time it was used. Similarly, by 
using \\n(PS, the point size at the time the macro was called is obtained. 

An example that does not involve numbers is the .NP macro (defined earlier) which had the request 

.tl ’left’center’right’ 

The fields could be made into parameters by using instead 
.tl ’\\*(LT’\\*(CT\\*(RT’ 

The title comes from three strings called LT, CT, and RT. If these are empty, the title will be a blank line. Nor¬ 
mally, CT would be set with 

.ds CT - % - 
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to give just the page number between hyphens. A user could supply private definitions for any of the strings. 
4.12 Conditionals 

Suppose it is desired that the .SH macro leave two extra inches of space just before Section 1, but nowhere 
else. The cleanest way to do that is to test inside the .SH macro whether the section number is 1, and add some 
space if it is. The .if command provides the conditional test that can be added just before the heading line is 
output: 

.if \\n(SH*l .sp 2i \ " first section only 

The condition after the .if request can be any arithmetic or logical expression. If the condition is logically 
true or arithmetically greater than zero, the rest of the line is treated as if it were text (a request in this case). 
If the condition is false, zero, or negative, the rest of the line is skipped. 

It is possible to do more than one request if a condition is true. For example, if several operations are to 
be done prior to Section 1, the .Si macro is defined and invoked when Section 1 is almost complete (as deter¬ 
mined by an if). 

.deSl * 

— processing for section 1 

.'de SH 

if \\n(SH-l .SI 


An alternate way is to use the extended form of the if request, e.g.: 

if \\n(SH«l \{— processing 
for section 1 —\} 

The braces, \{ and \}, must occur in the positions shown or unexpected extra lines will be in the output The 
troff processor also provides an “if-else” construction. 

A condition can be negated by preceding it with !. The same effect as above is obtained (but less clearly) 
by using 

.if !\\n(SHM .Si 

There are a handful of other conditions that can be tested with .if. For example: 

.if e .tl ‘left top’ center top ‘right top’ 

.if 0 .tl ‘left top’ center top ‘right top’ 

gives facing pages different titles, depending on whether the page number is even or odd, when used inside an 
appropriate new page macro. 

Two other conditions are t and n, which tells whether the formatter is troff or nroff: 

.if t troff stuff ... 
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.if n nroff stuff ... 

String comparisons may be made in a .if request. 

.if ’stringl’string2’ stuff 

executes the program stuff if stringl is the same as string 2 The character separating the strings can be any¬ 
thing reasonable that is not contained in either string. The strings themselves can reference strings with \ m , 
arguments with \$, etc. 

4.13 Environments 

There is a potential problem when going across a page boundary: parameters like size and font for a page 
title may be different from those in effect in the text when the page boundary occurs. A general way to deal 
with this and similar situations is provided by the troff formatter. 

There are three environments. Each has independently selectable versions of many parameters associated 
with processing, including size, font, line and title lengths, fill/no-fill mode, tab stops, and partially collected 
lines. Thus the titling problem may be solved by processing the main text in one environment and titles in an¬ 
other with its own suitable parameters. 

The ,ev n request shifts to environment n (n must be 0,1, or 2). The .ev request with no argument returns 
to the previous environment. Environment names are maintained in a stack, so calls for different environments 
may be nested and unwound consistently. 

If the main text is processed in environment 0 where the troff formatter begins by default, the new page 
macro, .NP, can then be modified to process titles in environment 1, e.g. 


.de NP 
.ev 1 
.It 6i 
itR 
.ps 10 


\ " shift to new environment 
\ " set parameters here 


any other processing 

\ " return to previous environment 


.ev 


It is also possible to initialize the parameters for an environment outside the .NP macro, but the version shown 
keeps all the processing in one place and is easier to understand and change. 

4.14 Diversions 

There are numerous occasions in page layout when it is necessary' to store some text for a period of time 
without actually printing it. Footnotes are the most obvious example. Text of the footnote usually appears in 
the input well before the place on the page is reached where it is to be printed. The place where it is output nor¬ 
mally depends upon the magnitude of the footnote. This implies that there must be a way to process the footnote, 
at least enough to decide its size without printing it. 

A mechanism called a diversion is provided by the troff formatter for doing this processing. Any part of 
the output may be diverted into a macro instead of being printed; and at some convenient time, the macro may 
be put back into the input. 

The .di xy request begins a diversion. All subsequent output is collected into the macro xy until the .di 
request with no arguments is encountered. This terminates the diversion. Processed text is available at any time 
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thereafter by giving the .xy request. The vertical size of the last finished diversion is contained in the built-in 
number register dn. For instance, to implement a keep-release operation so that text between the macros .KS 
and .KE will not be split across a page boundary (as for a figure or table), the following applies: 

• When a .KS is encountered, the output is diverted to determine its size. 

• When a ,KE is encountered and if the diverted text will fit on the current page, it is printed there. If 
the diverted text does not fit on the current page, it is printed at the top of the next page. 

The definitions of the .KS and .KE macros are as follows: 


.de KS 

\ " start keep 

.br 

\ " start fresh line 

.ev 1 

\ " collect in new environment 

ii 

\ " make it filled text 

.diXX 

\ " collect in XX 

!de KE 

\ " end keep 

.br' 

\ " get last partial line 

.di 

\ " end diversion 

.if \\n(dn>«\\n(.t .bp 

V bp if does not fit 

.nf 

\" bring it back in no-fill 

.XX 

\" text 

.ev 

\" return to normal environment 


The number register nl indicates the current position on the output page. Since output was being diverted, 
it remains at its value when the diversion started. The dn register contains the amount of text in the diversion. 
The distance to the next trap is in the built-in register .t. It is assumed that the next trap is at the bottom margin 
of the page. If the diversion is large enough to go past the trap, the .if is satisfied; and a .bp request is issued. 
In either case, the diverted output is brought back with .XX. It is essential to bring it back in no-fill mode so 
the troff formatter will do no further processing on it. 

This is not the most general keep-release operation nor is it robust in the face of all conceivable inputs. It 
would require more space than available to display it in full generality. This manual is not intended to teach 
everything about diversions, but to sketch out enough so that existing macro packages can be read with some 
comprehension. 

5. NROFF/TROFF Tutorial ExamplM 

Although the nroff and troff formatters have by design a syntax reminiscent of earlier text processors 
with the intent of easing their use, it is usually necessary to prepare at least a small set of macro definitions 
to describe most documents. Such common formatting needs such as page margins and footnotes are deliber- 
ately not built into the nroff and troff formatters. Instead, the macro and string definition, number register, 
diversion, environment switching, page-position trap, and conditional input mechanisms provide the basis for’ 
user-defined implementations. 

Examples in the following text are intended to be useful and somewhat realistic but will not necessarily 
cover all relevant contingencies. Explicit numerical parameters are used to make the examples easier to read 
and to illustrate typical values. In many cases, number registers would be used to reduce the number of places 
where numerical information is kept and to concentrate conditional parameter initialization data that depends 
on whether the troff or nroff formatter is being used. 

5.1 Page Margins 

Header and footer macros are defined to describe the top and bottom page margin areas, respectively. A 
trap is planted at page position 0 for the header and at —N(N from the page bottom) for the footer. A simple 
header and footer macro definition is 
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.de hd 

\" define header 

’sp li 

\" end definition 

.de fo 

\" define footer 

’bp 

\" end definition 

O 

Si r—4 

o 1 
si si 
Z Z 



This example provides blank 1-inch top and bottom margins. The header will occur on the first page, only if 
the definition and trap exist prior to the initial pseudopage transition. In fill mode, the output line that springs 
the footer trap was typically forced out because some part or whole word did not fit on it. If anything in the 
footer and header that follows causes a break, that word or part word will be forced out. In this and other exam- 
pies requests like bp and tp that normally cause breaks are invoked using the no-break control character (). 
When the header/footer design contains material requiring independent text processing, the environment may 
be switched to avoid interaction with running text. 

A more realistic example follows: 

.in +4 
.de hd 

.if t .tl \(rn"\(rn' 

.if \\n%>l 
’sp t0.5i—1 
.tl 
.ps 
it 

•vs \j 
’sp ll.Oi 
ms 

.de fo 
.ps 10 
itR 
.vs 12p 
.if \\n%-l 
'sp l\\n(.pu—0.5i-l 
.tl 
’bp 

.wh 0 hd 
.wh — li fo 

This example sets the size, font, and base-line spacing parameters for the header/footer material. Parameters 
are restored to their original values when the header or footer is completed. The material in this case is a page 
number at the bottom of the first page and at the top of the remaining pages. If the troff formatter is used, 
a cut mark is drawn in the form of root-eri s at each margin. The sp’s refer to absolute positions to avoid depen¬ 
dence on the base-line spacing. Another reason for the sp in the footer is that the footer is invoked by printing 
a line whose vertical spacing swept past the trap position by possibly as much as the base-line spacing. The 
no-space mode is turned on at the end of hd to render ineffective accidental occurrences of sp at the top of the 
running text. 

The above method of restoring size, font, etc. presupposes that such requests (that set previous : value) are 
not used in the running text. A better scheme is to save and to restore both the current and previous values 


\" header 
\ " troff cut mark 

\ " tl base at 0.5i 

\ " centered page number 

\ " restore size 

\ " restore font 

\ " restore vs 

\ " space to l.Oi 

\ " turn on no-space mode 

\" footer 

\ " set footer/header size 
\ " set font 

\ H set base-line spacing 

\ " tl base 0.5i up 
\ " first page number 
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as shown for size in the following; 


.de fo 

.nr si \\n(.s 

\" current size 

.ps 

.nr s2 \\n(.s 

\ " previous size 

— 

\" rest of footer 

.de hd 

— 

\ " header stuff 

.ps \\n(s2 

\ " restore previous size 

ps \\n(sl 

\" restore current size 


Page numbers may be printed in the bottom margin 
ejection: 


by a separate macro triggered during the footer’s page 


.de bn \ " bottom number 

.tl % -” \ " centered page number 


.wh —0.5i—lv bn \ " tl base 0.5i up 

5.2 Paragraphs and Headings 


Housekeeping associated with starting a new paragraph should be collected in a paragraph macro that docs 
the desired preparagraph spacing, forces the correct font, size, base-line spacing, and indent; checks that enough 
space remains for more than one line; and requests a temporary indent. 


•de pg 
.br 
itR 
.ps 10 
.vs 12p 
.inO 
.sp 0.4 

.ne l+\\n(.Vu 
.ti 0.2i 


\" paragraph 
\" break 
\ " force font, 

\" size, 

\" spacing, 

\" and indent 
\" prespace 

\ " want more than 1 line 
\ " temp indent 


The first break in pg will force out any previous partial lines and must occur before the .vs request The 
forcing of font, size, base-line spacing, and indent is partly a defense against prior error and partly to permit 
hings like section heading macros to set parameters only once. The prespacing parameter is suitable for the 
f r °f f form £tter, a larger space, at least as big as the output device vertical resolution, would be more suitable 
m the nroff formatter. The choice of remaining space to test for in the .ne is the smallest amount greater than 
one line (the .V is the available vertical resolution). 


A macro to automatically number section headings might look like: 

•de sc \ " section 

— \ " force font, etc. 

.sp 0.4 \ " prespace 

.ne 2.4+\\n(.Vu \ " want 2.4+ lines 

li 

\\n+S. 


.nr S 0 1 


\ " initial S 


f0l !r, d „ by - hC SeCti ° n , head j ng textl followed b y PS- -ne test value includes one line of 
heading. 0.4 line in the following pg, and one line of the paragraph text. A word consisting of the next section 
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number and a period is produced to begin the heading line. The format of the number may be set by the .af re¬ 
quest. 


Another common form is the labeled, indented paragraph where the label protrudes left into the indent 
space. 


.de lp 
•Pg 

.in 0.5i 
.ta 0.2i 0.5i 
.ti 0 

\t\\$\l\t\c 


\" labeled paragraph 

\" paragraph indent 
\" label, paragraph 

\" flow into paragraph 


The intended usage is 
.lp label 

The label will begin at 0.2 inch and cannot exceed a length of 0.3 inch without intruding into the paragraph. 
The label could be right adjusted against 0.4 inch by setting the tabs instead with .ta 0.4iR 0.5i. The last line 
of lp ends with \c so that it will become a part of the first line of the text that follows. 

5.3 Multiple Column Output 

The production of multiple column pages requires the footer macro to decide whether it was invoked by 
other than the last column, so that it will begin a new column rather than produce the bottom margin The 
header can initialize a column register that the footer will increment and test. The following is arranged for 
two columns but is easily modified for more: 


.de hd 

\" header 

.nr cl 0 1 

\ " init column count 

.mk 

\" mark top of text 

•de fo 

\" footer 

.ie \\n+(cl<2 \{\ 


.po +3.4i 

\ " next column; 3.1+0.3 

.rt 

\" back to mark 

.ns \} 

\ " no-space mode 

•el \{\ 


.po \\nMu 

\ " restore left margin 

’bp \} 


!il 3.1i 

\ " column width 

Jir M \\n(.o 

\ " save left margin 


Typically, a portion of the top of the first page contains full width text; the request for the narrower line 
length, as well as another .ink request, will be made where the 2-column output is to begin. 

5.4 Footnote Processing 


The footnote mechanism is used by imbedding the footnotes in the input text at the point of reference 
demarcated by an initial .fn and a terminal ,ef. 
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.fn 

Footnote text and control lines, 
.ef 


The following macro definitions cause footnotes to be processed in a separate environment and diverted for 
ater printing in the space immediately prior to the bottom margin. There is provision for the case where the 
last collected footnote does not completely fit in the available space: 


.de hd 


\" header 


.nr x 0 1 
.nr y 0-\\nb 
.ch fo -\\nbu 
.if \\n(dn iz 

.de fo 
.nr dn 0 
.if \\nx \{\ 

.ev 1 
.nf 
.FN 
.rm FN 

.if " \\nU" fy" .di 

.nr x 0 

.ev \} 

'bp 

.de fx 

.if \\nx .di fy 


\ " init footnote count 
\ " current footer place 
\" reset footer trap 
\ " leftover footnote 

\" footer 

\ " zero last diversion size 

\" expand footnotes in evl 
\ " retain vertical size 
\" footnotes 
\" delete it 

\ " end overflow diversion 
\ " disable fx 
\ " pop environment 


\ " process footnote overflow 
\ " divert overflow 


.de fn 
.da FN 
.ev 1 

.if \\n+x-l .fs 
ii 


\ " start footnote 
\ " divert (append) footnote 
\ " in environment 1 
\ " if first, include separator 
\ " fill mode 


\" 

\" 

V 

\" 


.de ef 
.br 

.nr z \\n(.v 
.ev 

.di \« 

.nr y -\\n(dn \ " 

.if \\nx-l .nr y -(\\n(.v-\\nz)\ \ 
.ch fo \\nyu \ 

.if (\\n(nl+lv)>(\\n(.p+\\ny)\ 

.ch fo \\n(nlu+lv \ • 


end footnote 
finish output 
save spacing 
pop ev 

end diversion 
new footer position 
’ uncertainty correction 
" y is negative 

it did not fit 


.de fs 

\" separator 

\rir 

\ " 1 inch rule 

.br 

.de fz 

\ " get leftover footnote 

.fn 
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.nf 

\" 

•fy 

V 

.ef 


.nr b l.Oi 

• . \" 

.wh 0 hd 

\" 

.wh 12i fo 

\" 

.wh -\\nbu fx 

\" 

.ch fo -\\nbu 

\" 


retain vertical size 


bottom margin size 
header trap 

footer trap, temp position 
fx at footer position 
conceal fx with fo 

• The header macro (hd) initializes a footnote count register x and sets both the current footer trap posi¬ 
tion register y and the footer trap itself to a nominal position specified in register b. 

• If the register dn indicates a leftover footnote, the fz macro is invoked to reprocess it 

. The footnote start macro (fn) begins a diversion (append) in environment 1 and inc [ e ^ n ^ th ® 

count register x; if the count is one, the footnote separator macro (fs) is interpolated. The separator 
is kept in a separate macro to permit user redefinition. 

• The footnote end macro (ef) restores the previous environment and ends the diversion after saving spac- 
ing size in register z. 

• Register y is decremented by the size of the footnote which is available in register dn. 

• On the first footnote, register y is further decremented by the difference in vertical base-line spacings 
of the two environments. This prevents late triggering of the footer trap from causing the last line of 
the combined footnotes to overflow. 

• The footer trap is set to the lower of y or the current page position (nl) plus one line to allow for printing 
the reference line. 

• If indicated by x, the footer fo rereads the footnotes from FN in no-fill mode in environment 1 and de¬ 
letes FN If the footnotes were too large to fit, the macro fx will be trap-invoked to redivert the ove 
into fy, and the register dn will later indicate to the header whether or not fy is empty. 

• Both fo and fx macros are planted in the nominal footer trap position in an order that causes fx to be 
concealed unless the fo trap is moved. 

• The footer terminates the overflow diversion (if necessary) and zeros x to disable fx. This is 

the uncertainty correction, together with a not-too-late triggering of the footer, can result in footnote 
macros finishing before reaching the fx trap. 


5.5 Last Page 

After the last input file has ended, nroff and troff formatters invoke the end macro, if any, and eject the 
remainder of the page. 


,de en \ " end-macro 

\c 

’bp 


.em en 


During the eject, any traps encountered are processed normally. At the end of this last page, processing termi¬ 
nates unless a partial line, word, or partial word remains. It it is desired that another page be started, the end- 
macro will deposit a null partial word and effect another last page. 
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TABLE FORMATTING PROGRAM 


1. Introduction 

The tbl program is a document formatting preprocessor for the formatter which makes fairly complex ta- 
. bl * s e J? y “\ specify and , e " te J r - Tabl , es consist of columns which may be independently centered, right-adjusted, 
left-adjusted, or aligned by decimal points. Headings may be placed over single columns or groups of columns 
A table entry may contain equations or consist of several rows of text. Horizontal or vertical lines may be drawn 
as desired in the table, and any table or element may be enclosed in a box. 

A description of a table is put by the tbl program into a troff formatter (the nroff and/or troff processor 
will be referred to synonymously as “formatter”) list of requests that prints the table. The tbl program isolates 
a portion of a job that can be successfully handled and leaves the remainder for other programs. Thus tbl may 
be used with the equation formatting program (eqn) and/or various formatter lavout macro packages without 
function duplication. 


2. Usage 

On the UNIX operating system, the tbl program can be run on a simple table with the command 
tbl filename I troff 


For more complicated use, where there are several input files containing equations and ms or mm macro re 
quests as well as tables, the normal command is 

tbl filel file2 .. .leqnltroff -ms 


The usual options may be used on the troff formatter and eqn commands. Usage of the nroff formatter is simi¬ 
lar to that of troff but only TELETYPE* Model 37 and Diablo-mechanism (DASI or GSI) terminals can print 
boxed tables. If a file name is the standard input is read at that point. 


For the convenience of users employing line printers without adequate driving tables or post-filters, there 
is a special -TX command-line option to tbl which produces output that does not have fractional line motions 
The only other command-line options recognized by tbl are -ms and -mm. They are turned into commands 
to fetch the corresponding macro files. It is usually more convenient to place these arguments on the troff 
formatter part of the command line, but they are accepted by tbl as well. 


When eqn and tbl programs are used together on the same file, tbl should be used first. If there are no 
equations within tables, either sequence works. It is usually faster to execute tbl first since eqn normally pro¬ 
duces a larger expansion of the input However, if there are equations within tables (using the delim option in 
eqn), tbl must be executed first or the output will be scrambled. Use of equations in n-style columns should 
be avoided since tbl attempts to split numerical format items into two parts. The delim(xx) table option pre¬ 
vents splitting numerical columns within delimiters. For example, if the eqn delimiters are $5, giving delimft 
5) causes a numerical column such as 1245 $± 16$ to be divided after 1245, not after 16. 

The tbl program accepts up to 35 columns; the actual number that can be processed may be smaller depend¬ 
ing on availability of troff formatter number registers. Number register names used by tbl must be avoided 
within tables. These include 2-digit numbers from 31 to 99 and strings of the form 4x; 5* #x, x+ x\ ~x, and 
at-, where xis any lowercase letter. The names ##, and #~ are also used in certain circumstances’. To con¬ 
serve register names, the n and a key letters (key letters are introduced in the “Format Section” part that fol¬ 
lows) share a register; hence, the restriction that they may not be used in the same column. 

As an aid in writing layout macros, tbl defines a number register TW which is the table width. The TW 
number register is defined by the time the ,TE macro is invoked and may be used in the expansion of that macro. 
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More importantly, to assist in laying out multipage boxed tables, the macro T# is defined to produce the bottom 
lines and side lines of a boxed table and then be invoked at its end. By use of this macro in the page footer, a 
multipage table can be boxed. In particular, the ms and mm macros can be used to print a multipage boxed table 
with a repeated heading by giving the argument H to the .TS macro. If the table start macro is written 

.TSH 

a line of the form 
.TH 


must be given in the table after any table heading (or at the start if none). Material up to the .TH is placed 
at the top of each page of the table. The remaining lines in the table are placed on several pages as required. 
This is not a feature of tbl but of the ms and mm macros. 

3. Input Commands 

Input to tbl is text for a document with tables preceded by a .TS (table start) command and followed by 
a .TE (table end) command. The tbl program processes the tables, generates formatting requests, and leaves 
the text unchanged. The .TS and .TE lines are copied so that troff formatter layout macros (such as memoran¬ 
dum formatting macros) can use these lines as delimiters. Arguments on the .TS or .TE lines are copied, but 
otherwise ignored, and may be used by document layout macro requests. 

The format of the input is 

text 

.TS 

table 

.TE 

text 

.TS 

table 

.TE 

text 


The format of each table is 
.TS 

options ; 
format. 
data 
.TE 

Each table is independent and contains; 

• Global options 

• A format section describing individual columns and rows of the table 

• Data to be printed. 

The format section and data are always required but not the options. 
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3.1 Global Option* 

th. TS u™ Vnd*™„« r!r th ‘ wh0,e “ ble - U thi ’ Hue ”>“« imawdiMely follow 

not^wJ 8 a d ”? U8t *^f tai vf 1#t ° f 0ptl0n names ,eparated b y •paces, tabs, or commas and must be termi¬ 
nated by a semicolon. Allowable options are: 

* center-center table (default is left-adjust) 

o expand—make table as wide as current line length 

* box—enclose table in a box 

* allbox—enclose each item of table in a box 
o doublebox—enclose table in two boxes 

o tab (x)—separate data items by using x instead of tab 
o Unesize (n)-set lines or rules (e.g., from box) in n-point type 
o delim (xy)—recognize x and y as eqn delimiters. 

The tbl program tries to keep boxed tables on one page by issuing appropriate .ne (need) requests. These re¬ 
quests are calculated from the number of lines in the tables. If there are spacing requests embedded in the input 
the ^ne requests may be inaccurate. Normal troff formatter procedures, such as keep-release macros, are used 

m that case. If a multipage boxed table is required, macros designed for this purpose (.TS H and TH) should 
be used. 

3.2 Format Section 

The format section of the table specifies the layout of the columns. Each line in the format section corre¬ 
sponds to one line of table data (except that the last format line corresponds to all following data lines up to 
any additional .T& command line). Each line contains a key letter for each column of the table. Key letters 
for each column may be separated by spaces or tabs for readibility purposes. Key letters are: 


L or 1 
R or r 
C or c 
N or n 

A or a 

S or s 


Indicates a left-adjusted column entry. 

Indicates a right-adjusted column entry. 

Indicates a centered column entry. 

Indicates a numerical column entry. Numerical entries are aligned so that the units digits 
of numbers line up. 

Indicates an alphabetic subcolumn. All corresponding entries are aligned on the left and 
positioned so that the widest entry is centered within the column. 

Indicates a spanned heading. The entry from the previous column continues across this col¬ 
umn (not allowed for the first column of the table). 

Indicates a vertically spanned heading. The entry from the previous row continues down 
through this row (not allowed for the first row of the table). 

Hot n h ^^ er , iCal ^° 1U v mn ali 8? ment is specified, a location for the decimal point is sought. The rightmost 
dot (.) adjacent to a digit is used as a decimal point. If there is no dot adjoining a digit, the rightmost digit is 
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used as a units digit. If no alignment is indicated, the item is centered in the column. However, the special non¬ 
printing character string \& may be used to override dots and digits or to align alphabetic data. This string 
lines up where a dot normally would and then disappears from the final output. In the following example, items 
shown in the left column will be aligned (in a numerical column! as shown in the right column: 


13 

13 

4.2 

4.2 

26.4.12 

26.4.12 

abcdefg 

abcdefg 

abcdefg\& 

abcdefg 

43\&3.22 

433.22 

749.12 

749.12 


If numerical data are used in the same column with wider L (the capital L key letter is used instead of lower¬ 
case for readability) or r-type table entries, the widest number is centered relative to the wider L or r items. 
Alignment within the numerical items is preserved. This is similar to the behavior of a-type data. Alphabetic 
subcolumns (requested by the a key letter) are always slightly indented relative to L items. If necessary, the 
column width is increased to force this. This is not true for n-type entries. 

Note: The n and a items should not be used in the same column. 

The end of the format section is indicated by a period. The layout of key letters in the format section resem¬ 
bles the layout of the actual data in the table. Thus, a simple 3-column format might appear as 

css 

Inn. 

The first line of the table contains a heading centered across all three columns. Each remaining line contains 
a left-adjusted item in the first column followed by two columns of numerical data. A sample table in this for¬ 
mat is: 


OVERALL TITLE 


Item-a 

34.22 

9.1 

Item-b 

12.65 

.02 

Items: c,d,e 

23 

5.8 

Total 

69.87 

14.92 


Instead of listing the format of successive lines of a table on consecutive lines of the format section, succes¬ 
sive line formats may be given on the same line, separated by commas. The format for the above example could 
be written: 


c s s, 1 n n. 

Additional features of the key letter system are: 

• Horizontal lines—A key letter may be replaced by underscore (_) to indicate a horizontal line in place 
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of the column entry or equal (-) to indicate a double horizontal line. If an adjacent column contains 
a horizontal line or if there are vertical lines adjoining this column, the horizontal line is extended to 
meet nearby lines. If any data entry is provided for this column, it is ignored and a warning message 


• Vertical lines—A vertical bar (|) placed between column key letters will cause a vertical line between 
the corresponding columns of the table. A vertical bar to the left of the first key letter or to the right 
of the last one produces a. line at the edge of the table. If two vertical bars appear between key letters 
a double vertical line is drawn. 

• Space between columns—A number may follow the key letter indicating the amount of separation be¬ 
tween this column and the next column. The number specifies the separation in ens. One en is about 
the width of the letter “n”. More precisely, an en is the number of points (1 point = 1/72 inch) equal 
to half the current type size. If the expand option is used, these numbers are multiplied by a constant 
such that the table is as wide as the current line length. The default column separation number is 3. 
If the separation is changed, the worst case (largest space requested) governs. 

• Vertical spanning-Ve rtically spanned items extending over several rows of the table are centered in 
their vertical range. If a key letter is followed by t or T, any corresponding vertically spanned item will 
begin at the top line of its range. 

• Font changes—A key letter followed by a string containing a font name or number preceded by the letter 
f or F indicates that the corresponding column should be in a different font from the default font (usu¬ 
ally Roman). All font names are one or two letters. A 1-letter font name should be separated from what¬ 
ever follows by a space or tab. The single letters B, b, I, and i are shorter synonyms for fB and fl. Font- 
change requests given with the table entries override these specifications. 

• Point size changes—A key letter followed by p or P and a number indicates the point size of the corre¬ 
sponding table entries. If the number is a signed digit, it is taken as an increment or decrement from 
the current point size. If both a point size and a column separation value are given, one or more blanks 
must separate them. 

• Vertical spacing changes—A key letter followed by v or V and a number indicates the vertical line spac¬ 
ing used within a multiline table entry. The number may be a signed digit, in which case it is taken as 
an increment or decrement from the current vertical spacing. A column separation value must be sepa¬ 
rated by blanks or some other specification from a vertical spacing request. This request has no effect 
unless the corresponding table entry is a text block. 

• Column width indication —A key letter followed by w or W and a width value in parentheses indicates 
minimum column width. If the largest element in the column is not as wide as the width value given 
after the w, the largest element is assumed to be that wide. If the largest element in the column is wider 
than the specified value, its width is used. The width is also used as a default line length for included 
text blocks. Normal troff formatter units can be used to scale the width value. The default value is ens 
if none are used. If the width specification is a unitless integer, the parentheses may be omitted. If an¬ 
other width value is given in a column, the last one controls the width. 

• Equal-width columns—A key letter followed by e or E indicates equal-width columns. All columns 
whose key letters are followed by e or E are made the same width. This permits a group of regularly 
spaced columns. 

• Staggered columns—A key letter followed by u or U indicates that the corresponding entry is to be 
moved up one-half line. This makes it easy to have a column of differences between numbers in an ad¬ 
joining column. The allbox option does not work with staggered columns. 

• Zero-width item —A key letter followed by z or Z indicates that the corresponding data item is to be 
ignored in calculating column widths. This may be useful in allowing headings to run across adjacent 
columns where spanned headings would be inappropriate. 
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• Default— Column descriptors missing from the end of a format line are assumed to be L. The longest 
line in the format section, however, defines the number of columns in the table. Extra columns in the 
data are ignored. 

The order of the features is immaterial. They need not be separated by spaces except as indicated to avoid 
ambiguities involving point size and font changes. Thus, a numerical column entry in italic font and 12-point 
type with a minimum width of 2.5 inches and separated by 6 ens from the next column could be specified as 

npl2w(2.5i)fl 6 

3.3 Doto To Be Printed 

Data for the table are input after the format section. Each table line is typed as one line of data. Very long 
input lines can be broken. Any line whose last character is a backslash (\) is combined with the following line 
(i.e., the \ vanishes). Data for different columns (table entries) are separated by tabs or by whatever character 
has been specified in the tab global option. There are a few special cases of data entries. 

• troff commands within tables—An input line beginning with a dot and followed by anything but a num¬ 
ber (.xx) is assumed to be a request to the formatter and is passed through unchanged,.retaining its posi¬ 
tion in the table. For example, a space within a table may be produced with the .sp request in the data. 

• Full width horizontal lines— An input line containing only the _ (underscore) character or = (equal 
sign) is taken to be a single or double line, respectively, extending the full width of the table. 

• Single column horizontal lines— An input table entry containing only the _ character or the = is taken 
to be a single or double line extending the full width of the column. Such lines are extended to meet hori¬ 
zontal or vertical lines adjoining this column. To obtain these characters explicitly in a column, they 
should be preceded by a \& or followed by a space before the usual tab or newline character. 

• Short horizontal lines- An input table entry containing only the string \_ is assumed to be a single 
line as wide as the contents of the column. It is not extended to meet adjoining lines. 

• Repeated characters- An input table entry containing only a string of the form \Rx, where x is any 
character, is replaced by repetitions of the character x as wide as data in the column. The sequence is 
not extended to meet adjoining columns. 

• Vertically sp ann ed items —An input table entry containing only the \~ character string indicates that 
the table entry immediately above spans downward over this row. It is equivalent to a table format key 
letter of *. 

• Text blocks—In order to include a block of text as a table entry, precede it by T{ and follow it by T}. 
Thus, the sequence 

• • T{ 
block of 
text 
Tj. .. 

is the way to enter as a single entry in the table something that cannot conveniently be typed as a simple 
string between tabs. The T) (end delimeter) must begin a line. Additional columns of data may follow 
after a tab on the same line. 

Various limits in the troff program are likely to be exceeded if 30 or more text blocks are used in a table. 
This produces diagnostic messages such as “too many string/macro names or ‘too many number regis¬ 
ters”. 
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Text blocks are pulled out from the table, processed separately by the formatter, and replaced in the 
table as a solid block. 

If no line length is specified in the block of text or in the table format, the default is to use 
Lx C/(tf+ 1) 

where L is the current line length, Cis the number of table columns spanned by the text, and Nis the 
total number of columns in the table. 

Other parameters (point size, font, etc.) used in setting the block of text are: 

(a) Those in effect at the beginning of the table (including the effect of the .TS macro) 

(b) Any table format specifications of size, spacing, and font using the p, v, and f modifiers to the 
column key letters 

(c) troff requests within the text block itself (requests within the table data but not within the text 
block do not affect that block). 

Although any number of lines may be present in a table, only the first 200 lines are used in setting up the 
table. A multipage table may be arranged as several single-page tables if this proves to be a problem. 

When calculating column widths, all table entries are assumed to be in the font and size being used when 
the .TS command was encountered. This is true except for font and size changes indicated in the table format 
section or within the table data (as in the entry \s+3 data\fP\sO). Because arbitrary troff requests may be 
sprinkled in a table, care must be taken to avoid confusing width calculations. It is not possible to change the 
number of columns, the space between columns, the global options such as box, or the selection of columns to 
be made equal in width. 

4. Additional Command linos 

To change the format of a table after many similar lines, as with subheadings or summarizations, the .T& 
(table continue) command is used to change column parameters. It is not recognized after the first 200 lines 
of a table. The outline of such a table input is 

.TS 

options ; 

format 

data 

format 

data 

.T& 

format 

data 

.TE 

Using this procedure, each table can be close to its corresponding format line. 

5. Examples 


Figures 3.3 through 3.8 are included to show input and output information that illustrates the basic concepts 
of the tbl program. TheHTsymbol in the input data represents a tab character. Although each figure has a title 
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that indicates an option or feature, other examples of use may be gleaned from them, 
indicates the requesting of bold type print in the format area. 


For instance. Fig. 3.7 also 
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MATHEMATICS TYPESETTING PROGRAM 


1. Introduction 

Mathematical text is known in the publishing trade as “penalty copy" because it is slower, more difficult, 
and more expensive to set in type than any other kind of copy normally occurring in books and journals. One 
difficulty is the multiplicity of characters, sizes, and fonts. Many mathematical expressions-require an intimate 
mixture of Roman, italic, and Greek letters (in three sizes) and a number of special characters. Typesetting such 
expressions by traditional methods is essentially a manual operation. 

A second difficulty is the 2-dimensional character of mathematics. This is illustrated by expressions such 
as: 



dx 

-be * flU 


1 _. fae^-fb 

2mfaB ° g fae^+fb 


1 

m Vi 5 

-1 

mfaB 


tanh 4 ( -Jj-e") 
coth'H 


This example also shows line-drawing, built-up characters (such as braces and radicals), and a spectrum of posi¬ 
tioning problems. 

The eqn software for typesetting mathematics has been designed to be easy to learn and to use by people 
(for example, secretaries and mathematical typists) who know neither mathematics nor typesetting. The lan¬ 
guage can be learned in an hour or so since it has few rules and fewer exceptions. It interfaces directly with 
the phototypesetting language, the troff formatter, so mathematical expressions can be embedded in the run¬ 
ning text of a manuscript, and the entire document produced in one process. Typical mathematical expressions 
include size and font changes, positioning, line drawing, and other necessary functions to print according to 
mathematical conventions, and are done automatically. 

The syntax of the language is specified by a small context-free grammar, a compiler-compiler is used to 
make a compiler that translates this language into typesetting commands. Output may be produced on either 
a phototypesetter or on a terminal with forward and reverse half-line motions. So that mixtures of text and 
mathematics may be handled, the eqn program interfaces directly with text formatting programs. 

2. Usage 

On the UNIX operating system, the phototypesetter is driven by a text formatting program, troff, which 
was designed for typesetting text Facilities needed for printing mathematical expressions, such as arbitrary 
horizontal and vertical motions, line drawing, and font size changing are also provided. Syntax for describing 
these special operations is difficult to learn and difficult even for experienced users to type correctly. For this 
reason, the troff formatter is used as an assembly language by the eqn program which describes and compiles 
mathematical expressions. 

The eqn program will also produce mathematics on DASI and GSI terminals and on TELETYPE® Model 
37 terminals. Input is identical, but neqn and the nroff formatter are used instead of eqn and the troff 
formatter. Some things will not look as good because terminals do not provide the variety of characters, sizes, 
and fonts that a typesetter does, but the output is usually adequate for proofreading. 

Running a preprocessor is easy on the UNIX operating system. To typeset text stored in files, the following 
command is issued: 

eqnfiles I troff 
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The vertical bar connects the output of one eqn process to the input of another troff process. Any troff 
formatter options are located following the troff formatter part of the command. For example: 

eqn files I troff -ms 

A compatible version of eqn can be used on devices like TELETYPE* Model 37, DASI, and GSI terminals 
which have half-line forward and reverse capabilities. To print equations on a TELETYPE* Model 37, the fol¬ 
lowing command is used: 

neqn files I nroff 

The language for equations recognized by neqn is identical to that of eqn although the output is more restrict¬ 
ed. To use a GSI or DASI terminal as the output device, the following command is used: 

neqn files I nroff -Tx 

where x is the terminal type being used, such as 300 or 300S. 

The eqn and neqn programs can be used with the tbl program for typesetting tables that contain mathe¬ 
matics. 

tbl files I eqn I troff 

tbl files I neqn I nroff 
3. language 
3.1 Design 

The fundamental principle upon which the eqn language design is based is that the language should be easy 
to use by those who know neither mathematics nor typesetting. This principle implies: 

• Normal mathematical conventions about operator precedence, such as parentheses, cannot be used. To 
give special meaning to such characters means that the user has to understand what is being typed. The 
language should not assume that parentheses are always balanced. 

• There should be few rules, keywords, special symbols, and operators. This keeps the language easy to 
learn and remember. Furthermore, there should be few exceptions to the rules that do exist If some¬ 
thing works in one situation, it should work everywhere. If a variable can have a subscript then a sub¬ 
script can have a subscript, etc., without limit. 

• Standard things should happen automatically. When “x^y+z+l” is typed, “x=y+z+l" should be the re¬ 
sult Subscripts and superscripts should be printed automatically (With no special intervention) in ap¬ 
propriately smaller size. Fraction bars should be made the right length and positioned at the correct 
height. A mechanism for overriding default actions should exist but its application is the exception, 
not the rule. 

A secondary, but still important design goal is that the system should be easy to build and to change. To 
this end and to guarantee regularity, the language is defined by a context-free grammar. The compiler for the 
language was built using a compiler-compiler. 

The typist should have a reasonable picture (a 2-dimensional representation) of the desired final form, such 
as might be handwritten by the author of a paper. It is also assumed that the input is to be typed on a computer 
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terminal much like an ordinary typewriter. This implies an input alphabet of perhaps 100 characters, none of 


The troff processor performs work for the mathematics typesetting function. It is a powerful program, with 
a macro facility, text and arithmetic variables, numerical computation and testing, and conditional branching 
Text strings are passed to the troff formatter omitting the need for a separate storage management package 
The user need not be concerned with most details of the particular device and character set currently in use 
For example, the troff formatter computes the widths of all strings of characters; the user does not need to 
know about them. 


3.2 Structure 


The basic structure of the language is not original. Equations are pictured as a set of boxes, pieced together 
in various ways. For example, something with a subscript is a box followed by another box moved downward 
and shrunk an appropriate amount. A fraction is a box centered above another box, at the right altitude, with 
a line of correct length drawn between them. 

3.3 Mode of Operation 

Since the eqn program is useful for typesetting mathematics only, it interfaces with the underlying typeset¬ 
ting language in order to get intermingled mathematics and text. The standard mode of operation is that when 
a document is typed, mathematical expressions are input as part of the text but marked by delimiters, .EQ and 
.EN. The program reads this input and treats as comments those things which are not mathematics, passing 
them through untouched. At the same time, it converts mathematical inputs into troff formatter commands. 
The resulting output is passed directly to the formatter where comments and mathematical parts become text 
and/or formatter commands. 

4. User's Guide 

4.1 Delimiters 

The eqn preprocessor reads intermixed text and equations and passes its output to the troff formatter. 
Since the formatter uses lines beginning with a period as control words (.ce means “center the next output 
line”), eqn uses the .EQ macro to mark the beginning of an equation and the .EN macro to mark the end. The 
.EQ and .EN delimiters are passed through to the formatter untouched, so they can be used to center equations, 
number them automatically, etc. The troff and nroff formatter macro packages, -ms and —mm, allow equa¬ 
tions to be centered, indented, left-justified, and numbered. The —ms package centers (by default) equations. 
To left-justify an equation, the .EQ L macro is used. A .EQ I macro will indent the equation. Any of these se¬ 
quences can be followed by an arbitrary equation number placed at the right margin. For example, the input 

.EQ I (3.1a) 
x = f(y/2) + y/2 
.EN 


produces the output 

x = f(y/2) + y/2 

By default, however, .EQ and .EN are ignored by the troff formatter, so equations 

The .EQ and .EN macros can be supplemented by troff commands as desired. A 
can be produced with the input 


(3.1a) 

are printed in-line, 
centered display equation 


.ce 
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.EQ 

x sub i = y sub i ... 

.EN 

Since it is tedious to type .EQ and .EN around very short expressions (e.g., single letters), two characters 
can be defined to serve as the left and right delimiters of expressions. These characters are recognized anywhere 
in subsequent text. For example, if the left and right delimiters have both been set to #, the input 

Let fxi, fyi, and hi be positive 

produces 

Let x, y, and z be positive 

4.2 Spaces and New Lines 

4.2.1 Input Spaces 

Input is free form. Space and newline characters in the input are used by eqn to separate pieces of the input; 
they are not used to create space in the output Thus an input 

x = y 

+ z + 1 

produces 

x=y+z+l 

Free-form input is easier to type initially. Space and newline characters should be freely used to make input 
equations readable and easy to edit. Very long lines are hard to correct if a mistake is made. 

4.2.2 Output Spaces 

Extra white space can be forced into the output by several characters of various sizes. A tilde (%) gives a 
space equal to the normal word spacing in text, a circumflex (') gives half this much, and a tab charac¬ 
ter spaces to the next tab stop (tab stops must be set by troff commands). Spaces (or tildes, etc.) also 
serve to delimit pieces of input. For example, to get 

x = y + z 

the following expression is input 
x' = *y' + 'z 

4.3 Symbols, Special Names, and Greek Alphabet 

Mathematical symbols, mathematical names, and the Greek alphabet are known by eqn. For example: 
x=2 pi int sin ( omega t)dt 


produces 
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.\-”2;r|sin(wt)dt 


Spaces in the input are necessary to indicate that sin, pi, int, and omega are separate entities and should get 
special treatment. The eqn program looks up each string of characters in a table, and if found, gives it a transla¬ 
tion. Digits, parentheses, brackets, punctuation marks, and the following mathematical words are converted to 
Roman font 

sin cos tan sinh cosh tanh arc 
max min lim log In exp 
Re Im and if for det 

In the previous example, pi and omega become their Greek equivalents, int becomes the integral sign (which 
must be moved down and enlarged), and sin is output in Roman font, following conventional mathematical prac¬ 
tice. Parentheses, digits, and operators are output in Roman font. 

Spaces should be put around separate parts of the input. A common error is to type “f(pi)" without leaving 
spaces on both sides of the “pi”. As a result, eqn does not recognize pi as a special word, and it appears as “f(pi)" 
in the output A list of eqn names appears in Table 3.Z. Four-character troff names can also be used for any¬ 
thing eqn does not recognize, e.g., \(pl for the + sign. 

The only way eqn can deduce that some sequence of letters may be special is if that sequence is separated 
from the letters on either side of it This can be done by surrounding a special word by ordinary space, tab, or 
newline characters. Special words can also be made to stand out by surrounding them with tildes or circumflex¬ 
es, e.g.: 

x* = '2'pi'int'sin*('omega't')'dt 

is much the same as the previous example, except tildes separate words like sin, omega, etc., and also add an 
extra space per tilde. 


x = 2 t J sin ( ui t ) dt 

4.4 Subscripts and Superscripts 

Subscripts and superscripts are introduced by the keywords “sub” and “sup", 
x* + y k 

is produced by 

x sup 2 + y sub k 

The eqn program takes care of all size changes and vertical motions needed to make the hard copy look right. 
The words “sub” and “sup” must be surrounded by spaces. A space or tilde is used to mark the end of a subscript 
or superscript. Return to the original base line is automatic. 
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Multiple levels of subscripts or superscripts are allowed. Subscripted subscripts and superscripted 
superscripts such as: 

x sub i sub 1 

produces 


X; 


A subscript and superscript on the same thing are printed one above the other if the subscript comes first The 
construct ^“something sub something sup something” is recognized as a special case. 

x sub i sup 2 


is 

Other than this special case, “sub” and “sup” group to the right 
x sup y sub z 


generates 


not 

x’ t 

A common erroneous expression is of the form 
y = (x sup 2)+l 
which causes 


y=(x 2,+1 
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instead of the intended 
Y - (x2) +1 

The error is in omitting the space (<sp>) delimiting superscripts. The correct expression is 
y - ( x sup 2 ) + 1 

4.5 Braces 

Complicated expressions can be formed by using braces ({}) to keep objects together in unambiguous 
groups. Braces indicate what goes over what or what terms are to be grouped before applying another mathe¬ 
matical function. 

Normally, the end of a subscript or superscript is marked by a space (tab or tilde, etc.). If the subscript or 
superscript is something that has to be typed with spaces in it, braces are used to mark the beginning and end. 
The input 


e sup {i omega t} 


produces 


Braces can be used to force eqn to treat something as a unit or just to make the intent perfectly clear. 
Braces can occur within braces if necessary. The statement 
e sup {i pi sup {rho +1}} 

generates 



A general rule is that an arbitrarily complicated string enclosed in braces can be used in place of a single charac¬ 
ter (such as x). The eqn program administers formatting details. In all cases, the correct number of braces are 
to be used. Omitting one or adding an extra one causes eqn to complain. 

The braces convention is an example of the power of using a recursive grammar to define the language. It 
is part of the language that dictates that if a construct can appear in some context, then any expression within 
braces can also occur in that context. 

4.6 Fractions 

Fractions are specified with the keyword over. 
a+b over c+d+e = 1 

produces 
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a+b 

- -1 

c+d+e 

The line is made the correct length and positioned automatically. When there is both an “over" and a “sup” in 
the same expression, eqn performs the “sup” first. 

-b sup 2 over pi 


is 

7r 

4.7 Square Root* 

There is a sqrt operator for making square roots of the appropriate size, 
x = {-b ± sqrt{b sup 2 -4ac}J over 2a 

yields 


x= 


2a 


Since large radicals look poor on some typesetters, sqrt is not recommended for tall expressions. 
4.8 Summations, Integrals, and Similar Constructions 

Summations, integrals, and similar constructions are easy, 
sum from i=0 to {i= inf} x sup i 

produces 


/-X 



/- 0 


Braces indicate where the upper part i= inf begins and ends. None are necessary for the lower part i=0 because 
it contains no spaces. Braces will never hurt; but if “from” and “to” parts contain any spaces, braces must be 
put around them. 

The “from” and “to” parts are optional; but if both are used, they have to occur in that order. 
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Other useful characters can replace the sum in the above example. They are 
int prod union inter 
which become, respectively 


{ nun 


Since characters before the “from" can be anything, even something in braces, "from-to” can often be used in 
unexpected ways. 


is 


lim from {n -> inf) x sub n “0 


lim x„ =0 


4.9 Size and Font Changes 

Although eqn makes an attempt to use correct sizes and fonts, there are times when default assumptions 
are not what is wanted. Slides and transparencies often require larger characters than normal text. Thus size 
and font changing commands are also provided. By default, equations are set in 10-point type with standard 
mathematical conventions to determine what characters are in Roman and italic font. Size and font changes 
are made with size n and Roman, italic, bold, or fat operations. Like the “sub” and “sup” keywords, size and 
font changes affect only the string that follows and revert to the normal situation afterward. Thus: 

bold x y 
is 


xy 

Braces can be used if something more complicated than a single letter is to be affected. 

Legal sizes which may follow size are 

6, 7, 8, 9,10,11,12,14, 

16,18, 20, 22, 24, 28, 36. 

The size can also be changed by a given amount. For example: 
size +2 

makes the size two points larger. This has the advantage that knowledge of the current size is not necessarv. 

If fonts other than Roman, italic, and bold are to be used, the font X statement (X is a 1-character troff 
name or number for the font) can be used. Since eqn is tuned for Roman, italic, and bold, other fonts may not 
give as good an appearance. 
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The fat operation takes the current font and widens it by overstriking. 

If an entire document is to be in a nonstandard size or font, it is a nuisance to write out a size and font change 
for each equation. Accordingly, a global size or font can be set that thereafter affects all equations. The follow¬ 
ing statements would appear at the beginning of any equation to set the size to 16 and the font to Roman: 

.EQ 

gsize 16 
gfont R 

!en 

In place of R, any of the troff font names may be used. The size after gsize can be a relative change with + 
or 


Generally, gsize and gfont appear at the beginning of a document. They can also appear throughout a docu¬ 
ment The global font and size can be changed as often as needed; for example, in a footnote in which the size 
of equations should match the size of the footnote text. Footnote text is usually two points smaller than the 
main text. Global size should be reset at the end of the footnote. 

4.10 Diacritical Marks 

Diacritical marks, a problem in traditional typesetting, are straightforward. There are several words used 
to get funny marks on top of letters. 


x dot 

X 

x dotdot 

X 

x hat 

X 

x tilde 

X 

x vec 

J? 

x dyad 

X 

x bar 

X 

x under 

2 


The diacritical mark is placed at the correct height, and bar and under are made the right length for the entire 
construction. Other marks are centered. An example of an expression using diacritical marks is: 
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It is made by typing 

x dot under + x hat + y tilde 
+ X hat + Y dotdot ■ z+Z bar 

4.11 Quoted Text 


An input entirely within Quotes (“...”) is not subject to font changes or spacing adjustments normally done 
by the typesetting program. This provides for individual spacing and adjusting if needed. For example: 

italic " sin(x)" + sin (x) 


produces 

sin(x) + sin(x) 

Quotes are also used to get braces and other eqn keywords printed. 
" { size alpha }" 

prints 


and 


prints 


{ size alpha } 

roman " { size alpha }' 

{ size alpha} 


The construction is often used as a place-holder when grammatically eqn needs something, but noth¬ 
ing is actually wanted on the output. 


4.12 Aligning Equations 

Sometimes it is necessary to align a series of equations at a horizontal position, often at an equals sign. This 
is done with two operations called mark and lineup 

The word mark may appear once at any place in an equation. It remembers the horizontal position where 
it appeared. Successive equations can contain one occurrence of the word lineup. The place where lineup appears 
is made to line up with the place marked by the previous mark if at all possible. For example: 

.EQI 

x+y mark = z 

.EN 

.EQ I 

x ’ineup - 1 

.'Si* 

produces 


x+y = z 
x = 1 
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W hen eqn and -ms are used, either .EQ I or .EQ L should be used. The mark and lineup operations do not 
work with centered equations. Also, mark does not look ahead. 

x mark =1 

x+y lineup =z 

is not going to work because there is not room for the x+y part after the mark remembers where the x is. 
4.13 Big Brackets 

Keywords “left” and “right” are used to make braces, brackets, parentheses, and vertical bars the correct 
height. 

left [ x+y over 2a right ] = 1 

produces 



To get large brackets [], braces {}, parentheses (), and bars • around information that exists on more than 
one line, the left and right commands are used. 

left { a over b + 1 right} 

= left ( c over d right) 

+ left [ e right ] 



The resulting brackets are made large enough to cover whatever they enclose. Other characters can be used be¬ 
sides these, but they are not likely to look very good. One exception is the floor and ceiling characters. 

left floor x over y right floor 
<= left ceiling a over b right ceiling 

produces 
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largC k tha “. brack ! tS and P arentheses because they are made up of three, five, seven etc pieces 
the character s« is^rifdSpJT' L "*' ^ rieht ' ,arentheMS ofte ” look ^usc 

resulting brackets may be too large. If the le/tpar, is to be 

cally a right cannot exist without a corresponding left Instead the following input will do: 


left 


— right) 


The left " " means a “left nothing”, which satisfies the rules without hurting the output. 

4.14 Piles 


41-6 ° fte u USed with L another facilit y- ca Hed piles, which make vertical piles of objects 
E ements of the pile (there can be any number) are centered one above another, at the right height for most 
purposes. The keyword above la used to separate the pieces; braces are used atound toe eftle lS eLTb 
of a pile can be as complicated as needed, even containing more piles. 

Three other forms of pile exist* 


• lpile makes a pile with the elements left-justified 

• rpile makes a right-justified pile 

• cpile makes a centered pile, just like pile. 

lSlTto%1 nS b6tWeen PieC69 13 SOmewhat larger for 1 - r - and c P iles than it is for ordinary piles. For ex¬ 


sign (.*•)■ < 


1 

0 

-1 


if x>0 
if x=0 
if x<0 


the following is input* 

sign (x) == left { 

rpile {1 above 0 above —1} 

* 'lpile {if above if above if} 

"lpile jx>0 above x=0 above x<0} 


o^ibo^i CO rhnv U p Cti ° n T^ ak . e3 . a 1Cft braCe Urge e f° Ugh t0 enclose the r P ile 1-1- w bich is a right-justified pile 
ot above ... above ... . The lpile construction makes a left-justified pile. ' 
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4.15 Matrices 

It is possible to make matrices. For example, to make a neat array like 



the following is the input: 
matrix { 

ccol { x sub i above y sub i} 
ccol { x sup 2 above y sup 2 } 

} 

This produces a matrix with two centered columns. Elements of the columns are then listed just as for a pile, 
each element separated by the word “above”. The lcol or rcol can also be used to left- or right-justify columns. 
Each column can be separately adjusted, and there can be as many columns as desired. 

The reason for using a matrix instead of two adjacent piles is if the elements of the piles are not all the 
same height they will not line up properly. A matrix forces them to line up because it looks at the entire struc¬ 
ture before deciding the spacing to use. 

Note: Each column must have the same number of elements. 

4.16 In-Line Equations 

In a mathematical document, it is necessary to follow mathematical conventions in display equations and 
in text. Making variable names (such as x) italic is one instance. Although this could be done by surrounding 
the appropriate parts with .EQ and .EN, the continual repetition of .EQ and JIN is a nuisance. Furthermore, 
with -mm, .EQ and JIN imply a displayed equation. 

The eqn program provides a shorthand notation for short in-line equations. Two characters can be defined 
to mark the left and right ends of a short in-line equation, and then expressions in the middle of text lines can 
be typed. If added to the beginning of the document, the three lines 

.EQ 

delim $$ 

.EN 

set both the left and right delimiter characters to dollar signs. A sample input would be 

Let $alpha sub i$ be the primary variable, and let $beta$ be zero. Then it can be shown that $x 
sub 1$ is $>=0$. 

This works as expected—space characters, newline characters, etc., are significant in the text, but not in the 
equation part itself. Multiple equations can occur in a single input line. 

Space is left before and after a line that contains in-line expressions so that a tall expression will not inter¬ 
fere with surrounding lines. 
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To turn off the delimiters: 

,EQ 

delim off 
.EN 


The following should be observed when using the in-line equations format: 

• Do not use braces, tildes, circumflexes, or double quotes as delimiters. 

• In-line font changes must be closed before in-line equations are encountered. 
4.17 Define* 


There is a definition facility, so a user can say 
define name 


at any time in the document Henceforth, any occurrence of the “name” in an expression will be expanded into 
whatever was inside the double quotes in its definition. This lets users tailor the language to their own specifica¬ 
tions. It is possible to redefine keywords like sup or over. For example, if the sequence 

x sub i sub 1 + y sub i sub 1 

appears repeatedly throughout a paper; retyping time can be saved each time by defining it 
define xy 'x sub i sub 1 + y sub i sub 1’ 

Makes xy a shorthand for whatever characters occur between the single quotes in the definition. Any character 
can be used instead of the quote to mark the ends of the definition as long as it does not appear inside the defini¬ 
tion. 

The above expression can now be input as follows: 

.EQ 

f(x) = xy... 

.EN 

Each occurrence of xy will expand into its definition. Spaces (or their equivalent) are to be left around the name 
when used. The eqn program will identify it as special. 

Although definitions can use previous definitions, as in: 

.EQ 

define xi ' x sub i ’ 
define xil ’ xi sub 1 ’ 

.EN 

it is erroneous to define something in terms of itself. For instance: 
define X ’ roman X ’ 

Since X is now defined in terms of itself, problems will result. However, if the following expression is used, the 
quotes protect the second X, and everything works fine. 

define X ’ roman " X " ’ 
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The eqn keywords can be redefined. By making / mean over with the following statement; 
define / ’ over ’ 

or by redefining over as / with: 

define over ’ / ’ 
the keyword is redefined. 

If different things are needed to be printed on a terminal and on the typesetter, symbols may be defined 
differently in neqn and eqn. This can be done with ndefine and tdefine A definition made with ndefine takes 
effect when running neqn. When tdefine is used, the definition only applies for eqn. Names defined with define 
apply to both eqn and neqn. 

4.18 Local Motions 

Although eqn tries to position things correctly on the paper, it occasionally needs tuning to make the output 
just right. Small extra horizontal spaces can be obtained with tilde and circumflex. By using back n and fwd 
n, small amounts are moved horizontally, where n is how far to move in 1/100’s of an em (an em is about the 
width of the letter “m”). Thus, back 50 moves back about half the width of an “m”. Similarly, things can be 
moved up or down with an up n and a down n. As with sub or sup, local motions affect the next thing in the 
input, and this can be something arbitrarily complicated if it is enclosed in braces. 

4.19 Precedence 

Precedence rules resolve the ambiguity in a construction like: 
a sup 2 over b 

The “sup” is defined to have a higher precedence than “over”. A user can force a particular analysis by placing 
braces around expressions. If braces are not used to group functions, eqn will do operations in the following 
order 

dyad vec under bar tilde hat dot dotdot 

fwd back down up 

fat roman italic bold size 

sub sup sqrt over 

from to 

The following operations group to the left 
over sqrt left right 
All others group to the right. 

5. Troubleshooting 

If a mistake is made in an equation, such as omitting a brace, having one too many braces, or having a “sup” 
with nothing before it eqn produces the following message: 

syntax error between lines x and y, file z 

where xand y are approximately the lines between which, the trouble occurred, and z is the name of the file 
in question. There are also self-explanatory messages that arise when a quote is omitted or eqn is run on a non¬ 
existent file. To check a document before printing 
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eqn files >/dev/null 

discards the output but prints the message. 

It is easy to leave out a dollar sign when used as delimiters. The checkeq program checks for misplaced 
or missing dollar signs and similar troubles. 

In-line equations can be only so big because of an internal buffer in the troff formatter. If a “word overflow” 
message is received, the limit has been exceeded. Printing the equation as a displayed equation usually causes 
the message to go away. The “line overflow” message indicates that an even bigger buffer has been exceeded. 
In this case, the equation must be broken into two separate ones, marking each with a .EQ ... .EN delimiter. 
The eqn program does not warn about equations that are too long for one line. 
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The following font examples are printed in 12-point, with a vertical spacing of 14-point, and with non- 
alphanumeric characters separated by V* em space. The original Special Mathematical Font was prepared 
for Bell Laboratories by Wang Laboratories, Inc., of Hudson, New Hampshire. The Times Roman, Italic, 
and Bold are among the many standard fonts available. 


Times Roman 

abcdef ghij klmnopqrstuvwxyz 

ABCDEFGHIJKLMNOPQRSTUVWXYZ 

1234567890 

!$%&()“* + - .,/:; = ?[]! 

• V* 3 /4 fi fl ff ffi ffl 0 f ' « ® ® 

Times Italic 

abcdefghijklmnopqrstu vwxyz 

ABCDEFGHIJKLMNOPQRSTUVWXYZ 

1234567890 

/$ %&()'•* + - ?[]\ 

• D-’-U K % lUlffffiffl ° ft • ® 

Times Bold 

abcdefghijklmnopqrstuvwxyz 

ABCDEFGHIJKLMNOPQRSTUVWXYZ 

1234567890 

!$%&( 

Special Mathematical Font 

" V_§‘/<> {}#@ + - =* 

aO'Y^c^TjdLxXfii'^oirpcsTVcpx^^ 
r_A6AEnST 4*0 

§v jx0etu-*i@ lomji nun 


Fig. 3.1 — Font Style Examples 
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Automatic sequence numbering of output lines may be requested with 
.nm. When in effect, a 3-digit, arabic number plus a digit-space is 
3 prepended to output text lines. Text lines are offset by four digit-spaces 
and otherwise retain their line length. A reduction in line length may 
be desired to keep the right margin aligned with an earlier margin. 
6 Blank lines, other vertical spaces, and lines generated by ,tl are not 
numbered. Numbering can be temporarily suspended with .nn or with a 
.nm followed by a later .nm +0. In addition, a line number indent / and 
9 the number-text separation S may be specified in digit-spaces. Further, 
it can be specified that only those line numbers that are multiples of 
some number M are to be printed (the others will appear as blank 
12 number fields). Table 3.S is a summary and explanation of output line 
numbering requests. 

As an example of output line numbering, paragraph portions of this 
15 figure are numbered with Af=3: .nm 1 3 was placed at the beginning; 
.nm was placed at the end of the first paragraph; and .nm +0 was 
placed in front of this paragraph; and .nm placed at the end. Line 
18 lengths were also changed (by \w'0000'u) to keep the right side 
aligned. Another example is .nm +5 5x3, which turns on numbering 
with the line number of the next line to be five greater than the last 
21 numbered line, with Af=5, spacing S untouched, and the indent I set to 3. 


Fig. 3.2 — Example of Output Lino Numbering 
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INPUT: 

.TS 
box; 
c c c 
111 . 

Language® Authors® Runs on 
.sp 

Fortran® Many® Almost anything 

Pl/1® IBM® 360/370 

C® BTL® 11/45,H6000,370 

BLISS® Carnegie-Mellon® PDP-10,11 

IDS® Honeywell® H6000 

Pascal® Stanford® 370 

.TE 


OUTPUT: 



Language 

Authors 

Runs on 

Fortran 

Many 

Almost anything 

PL/1 

IBM 

360/370 

C 

BTL 

11/45,H6000,370 

BLISS 

Carnegie-Mellon 

PDP-10,11 

IDS 

Honeywell 

H6000 

Pascal 

Stanford 

370 


Fig. 3.3 — Toblo Using "box" Option 
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INPUT: 

.TS 

ailbox; 
css 
c c c 
n n n. 

AT&T Common Stock 
Year® Price® Dividend 
1971® 41-54® $2.60 
2® 41-54® 2.70 
3® 46-55® 2.87 
4® 40-53® 3.24 
5® 45-52® 3.40 
6® 51-59® .95* 

.TE 

* (first quarter only) 


OUTPUT: 


AT&T Common Stock 

Year 

Price 

Dividend 

1971 

41-54 

$2.60 

2 

41-54 

2.70 

3 

46-55 

2.87 

4 

40-53 

3.24 

5 

45-52 

3.40 

6 

51-59 

.95* 


* (first quarter only) 



Fig. 3.4 — 


Table Using "allbox" Option 
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INPUT: 

.TS 
box; 
css 
ci cl c 
IIII n. 

Major New York Bridges 

Bridge® Designer® Length 

Brooklyn® J. A. Roebling® 1595 
Manhattan® G. Lindenthal® 1470 
Williamsburg® L. L. Buck® 1600 

QueensboroughtOPalmer &01182 
® Hornbostel 

®® 1380 

Triborough® 0. H. Ammann® _ 

®®383 

Bronx Whitestone® O. H. Ammann® 2300 
Throgs Neck® 0. H. Ammann® 1800 
.TE 


OUTPUT: 


Major New York Bridges 

Bridge 

Designer 

Length 

Brooklyn 

J. A. Roebling 

1595 

Manhattan 

G. Lindenthal 

1470 

Williamsburg 

L. L. Buck 

1600 

Queensborough 

Palmer & 

1182 


Hornbostel 


| 


1380 

Triborough 

O. H. Ammann 


1 

| 

383 

1 

Bronx Whitestone ! 

O. H. Ammann 

2300 

Throgs Neck 

O. H. Ammann 

1800 


Fig. 3.5 — Table Using "Vertical bar" Key Letter Feature 
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INPUT: 

.TS 

box; 

LLL 
L L _ 

LLILB 
L L _ 

LLL. 

january® february® march 

april® may 

june® july® Months 

august® September 

October® november® december 

.TE 


OUTPUT: 


january 

february 

march 

april 

may 


june 

july 

Months 

august 

September 


October 

november 

december 


Fig. 3.6 — TabU Using Horizontal Linos in Place of Key Letters 
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INPUT: 

.TS 

box; 

cfB s s s. 

Composition of Foods 

7t& 

c I c s s 
c I c s s 
c I c I c I c. 

Food® Percent by Weight 

V®_ 

\‘® Protein® Fat® Carbo- 
\‘® \‘® \‘® hydrate 

7t& 

11 n I n I n. 

Apples® .4® .5® 13.0 
Halibut® 18.4® 5.2® ... 
Lima beans® 7.5® .8® 22.0 
Milk® 3.3® 4.0® 5.0 
Mushrooms® 3.5® .4® 6.0 
Rye bread® 9.0® .6® 52.7 
.TE 


OUTPUT: 


Com] 

position of Foods 

Food 

Percent by Weight 

Protein 

Fat 

Carbo¬ 

hydrate 

Apples 

.4 

.5 

13.0 

Halibut 

18.4 

5.2 

• • • 

Lima beans 

7.5 

.8 

22.0 

Milk 

3.3 

4.0 

5.0 

Mushrooms 

3.5 

.4 

6.0 

Rye bread 

9.0 

.6 

52.7 


Fig. 3.7 — Table Using Additional Command Lines 
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INPUT: 

.TS 

allbox; 
cfl s s 

c cw(2i) cw(2i) 

111 . 

New York Area Rocks 
.sp 

Era® Formation® Age (years) 
Precambrian® Reading Prong® >1 billion 
Paleozoic® Manhattan Prong® 400 million 
Mesozoic® T{ 

.na 

Newark Basin, inch 

Stockton,Lockatong, and Brunswick 

formations 

.ad 

T}® 200 million 
Cenozoic® Coastal Plain® T{ 

.na 

On Long Island 30,000 years; 

Cretaceous sediments redeposited 
by recent glaciation 
.ad 
T} 

.TE 


OUTPUT: 


New York Area Rocks 

1--- 

Era 

Formation 

Age (years) 

Precambrian 

Reading Prong 

>1 billion 

Paleozoic 

! Manhattan Prong 

400 million 

Mesozoic 

i 

• 

1 Newark Basin, incl. Stockton, 

| Lockatong, and Brunswick 
formations 

200 million 

Cenozoic 

i 

Coastal Plain 

! 

1 

On Long Island 30,000 years; 
Cretaceous sediments 
redeposited by recent 
glaciation 
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TABLE 3.A 

CROSS REFERENCE 
REQUEST NAME TO TABLE NUMBER 


REQUEST 

NAME 

TABLE 

NUMBER 

REQUEST 

NAME 

TABLE 

NUMBER 

REQUEST 

NAME 

TABLE 

NUMBER 

REQUEST 

NAME 

TABU 

NUMBER 

ab 

3.Y 

el 

3.T 

Is 

3.H 

rd 

3.V 

ad 

3.G 

em 

3.J 

It 

3.R 

rm 

3.J 

af 

3.M 

eo 

3.0 

me 

3.X 

rn 

3J 

am 

3.J 

ev 

3.U 

ink 

3.F 

IT 

3.M 

as 

3.J 

ex 

3.V 

na 

3.G 

rs 

3.H 

bd 

3.C 

fc 

3.N 

ne 

3.F 

rt 

3.F 

bp 

3.F 

fi 

3.G 

nf 

3.G 

so 

3.W 

br 

3.G 

fl 

3.X 

nh 

3.Q 

sp 

3.H 

c2 

3.0 

fp 

3.C 

nm 

3.S 

ss 

3.E 

cc 

3.0 

ft 

3.C 

nn 

3.S 

sv 

3.H 

ce 

3.G 

he 

3.Q 

nr 

3.M 

ta 

3.N 

ch 

3.J 

hw 

3.Q 

ns 

3.H 

tc 

3.N 

CO 

3.X 

hy 

3.Q 

nx 

3.W 

ti 

3.1 

cs 

3.E 

ie 

3.T 

os 

3.H 

tl 

3.R 

cu 

3.0 

if 

3.T 

pc 

3.R 

tm 

3.X 

da 

3.J 

ig 

3.X 

Pi 

3.W 

tr 

3.0 

de 

3J 

in 

3.1 

pl 

3.F 

uf 

3.0 

di 

3J 

it 

3J 

pm 

3.X 

ul 

3.0 

ds 

3J 

lc 

3.N 

pn 

3.F 

vs 

3.H 

dt 

3J 

lg 

3.0 

po 

3.F 

wh 

3.J 

ec 

3.0 

11 

3.1 

ps 

3.E 
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TABLE 3.B 


ESCAPE SEQUENCES FOR 
CHARACTERS, INDICATORS, AND FUNCTIONS 


ESCAPE 

SEQUENCE 

MEANING 

\ (Note) 

\ (to prevent or delay the interpretation of \) 

\ * 

Acute accent; equivalent to \ (aa 

\ ' 

Grave accent; equivalent to \ (ga 

\ - 

Minus sign in the current font 

\ .(Note) 

Period (dot) (see do) 

\ <space> 

Unpaddable space-size space character 

\0 

Digit width space 

\l 

1/6 em narrow space character (zero width in the nroff formatter) 

\* 

1/12 em half-narrow space character (zero width in the nroff formatter) 

\ & 

Nonprinting zero width character 

\ ! 

Transparent line indicator 

\ ’’(Note) 

Beginning of comment 

\ $N 

Interpolate argument (1 < N >9) 

\ % 

Default optional hyphenation character 

\ (xx 

Character named xx 

\ *x,\*(xx(Note) 

Interpolate string x or xx 

\{ 

Begin conditional input 

\) 

End conditional input 

\ < newline > (Note) 

Concealed (ignored) newline character 

\ a(Note) 

Noninterpreted leader character 

\ b’abc...’ 

Bracket building function 

\ c 

Interrupt text processing 

\ d 

Forward (down) 1/2 em vertical motion (1/2 line in the nroff formatter) 

\ e 

Printable version of current escape character 

\ fx,\f(xx;\fJV 

Change to font named x or xx or position N 

\ gx,\g(xx 

Return the .af-type format of the register x or xx Returns nothing if x 
(xx) has not yet been referenced 

\ h’iV 

Local horizontal motion; move right N (negative left) 

\ jx,\j(xx 

Mark the current horizontal output position in register x or xx 

\ kx 

Mark horizontal input place in register x 

\ YNc’ 

Horizontal line drawing function (optionally with c) 

\ L’Nc’ 

Vertical line drawing function (optionally with c) 

\ nx;\n(xx(Note) 

Interpolate number register x or xx 

\ o’abc...’ 

Overstrike characters a, b, c, ... 

\ P 

Break and spread output line 

\ r 

Reverse 1 em vertical motion (reverse line in the nroff formatter) 

\ sN,\s±N 

Point-size change function 

\ t(Note) 

Noninterpreted horizontal tab 

\ u 

Reverse (up) 1/2 em vertical motion (1/2 line in the nroff formatter) 

\ v’JV 

Local vertical motion; move down N (negative up) 

\ w’ string 

Interpolate width of string 

\ x’N 

Extra line-space function (negative before, positive after) 

\ zc 

Print c with zero width (without spacing) 

\ X 

Any character not listed above 


Note: Interpreted in copy mode. 
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TABLE 3.C 


FONT CONTROL REQUESTS 


REQUEST 

FORM 

INITIAL 

VALUE 

IF NO 

ARGUMENT 

EXPLANATION 

.bd FN 

off 


Embolden font F by N-l units. Characters in font Fwill be 
artifically emboldened by printing each one twice, sepa¬ 
rated by N-l basic units. A reasonable value for N is 3 
when the character size is in the vicinity of 10 points. If N 
is missing, the embolden mode is turned off. The mode 
must still (or again) be in effect when the characters are 
physically printed. There is no effect in the nroff formatter. 

.bd S FN 

off 


Embolden special font when current font is F. The charac¬ 
ters in the special font will be emboldened whenever the 
current font is F. The mode must still (or again) be in effect 
when the characters are physically printed. There is no 
effect in the nroff formatter. \ jA , . £ c> ' - 

.fp NF 

R,I,B,S 

ignored 

Font position. A font named Fis mounted on position N(1 
through 4). It is a fatal error if Fis not known. The photo- 
typesetter has four fonts physically mounted. Each font 
consists of a film strip which can be mounted on a num¬ 
bered quadrant of a wheel. The default mounting sequence 
assumed by the troff formatter is R, I, B, and S on positions 

1, 2, 3, and 4. 

.ft F 

Roman 

previous 

Change to font F, where Fis x, xx, 1 through 4, or P. Font 

P means the previous font For font changes within a line 
of text, sequences \fx,\f(xx, or\fNcan be used. Relevant 
parameters are a part of the current environment 
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TABLE 3.D 

NAMING CONVENTION FOR NON-ASCII CHARACTERS 


Non-ASCII characters and minus on the standard fonts. 



Input 

Character 


Input 

Character 

Char 

Name 

Name 

Char 

Name 

Name 

• 


close quote 

fi 

\(fi 

fi 

• 


open quote 

fl 

\(fl 

11 

— 

\(em 

3/4 Em dash 

If 

\(ff 

ff 

- 

— 

hyphen or 

ffi 

\(Fl 

ffi 

• 

\(hy 

hyphen 

ffl 

\( FI 

ffl 

— 

\- 

current font minus 

• 

\(de 

degree 

• 

\(bu 

bullet 

t 

\(dg 

dagger 

□ 

\(sq 

square 

/ 

\(fm 

foot mark 

— 

\(ru 

rule 

c 

\(ct 

cent sign 

Va 

\(I4 

1/4 

• 

\(rg 

registered 

Vi 

\(I2 

1/2 

o 

\(co 

copyright 

Va 

\(34 

3/4 





Non-ASCII characters and , , and • on the special font. 



Input 

Character 


Input 

Character 

Char 

Name 

Name 

Char 

Name 

Name 

+ 

\(pl 

math plus 

K 

\Ck 

kappa 

— 

\(mi 

math minus 

\ 

\(*l 

lambda 

- 

\(eq 

math equals 

M 

\(*m 

mu 

• 

\c* 

math star 

V 

\(*n 

nu 

§ 

\(sc 

section 

{ 

\(*c 

xi 


\(aa 

acute accent 

0 

\(*o 

omicron 


\(ga 

grave accent 

T 

\Cp 

P* 


\( ul 

underrule 

P 

\(*r 

rho 

/ 

\(sl 

slash (matching backslash) 

a 

\Cs 

sigma 

n 

\Ca 

alpha 

s 

\(ts 

terminal sigma 

0 

\(*b 

beta 

T 

\(*t 

tau 

7 

M*g 

gamma 

V 

\Cu 

upsilon 

3 

\Cd 

delta 

<t> 

\Cf 

phi 

< 

\Ce 

epsilon 

X 

\(*x 

chi 

r 

\Cz 

zeta 

i 

\Cq 

psi 

*t 

\Cy 

eta 

Ul 

\('w 

omega 

e 

\(*h 

theta 

A 

\(*A 

Alpha* 

i 

\(*i 

iota 

• B 

\(*B 

Beta* 


tMapped into uppercase English letters in the font mounted on font position one. 
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NAMING CONVENTION FOR NON-ASCII CHARACTERS 



Input 

Character 


Input 

Character 

Char 

Name 

Name 

Char 

Name 

Name 

r 

\CG 

Gamma 


\(di 

divide 

A 

\C D 

Delta 

± 

\( + - 

plus-minus 

E 

\CE 

Epsilont 

U 

\(cu 

cup (union) 

2 

\cz 

Zeut 

n 

\(ca 

cap (intersection) 

H 

\(*Y 

Etat 

c 

\(sb 

subset of 

e 

\CH 

Theta 

D 

\(sp 

superset of 

i 

\C1 

lout 

C 

\(ib 

improper subset 

K 

\(*K 

Kappat 

2 

\(ip 

improper superset 

A 

\CL 

Lambda 

00 

\(>f 

infinity 

M 

\(*M 

Mut 

6 

\(pd 

partial derivative 

N 

\(*N 

Nut 

V 

\(gr 

gradient 

Z 

\cc 

Xi 


\(no 

not 

0 

\co 

OmicronT 

/ 

\(is 

integral sign 

n 

\CP 

Pi 

a 

\(pt 

proportional to 

p 

\CR 

Rhot 

0 

Vcs 

empty set 

2 

\cs 

Sigma 

€ 

\(mo 

member of 

T 

\CT 

Taut 

1 

\(br 

box vertical rule 

T 

\cu 

Upsilon 

X 

\(dd 

double dagger 

* 

\(*F 

Phi 

IT 

\(rh 

right hand 

X 

\cx 

Chit 


\(lh 

left hand 

♦ 

\CQ 

Psi 

@ 

Mbs 

Bell System logo 

n 

\(*W 

Omega 

1 

Mor 

or 

V 

\(sr 

square root 

0 

Mci 

circle 


\(rn 

root en extender 

f 

MU 

left top of big curly bracket 

> 

\(>- 

> - 

l 

Mlb 

left bottom 

< 

\«- 

ep¬ 

1 

Mrt 

right top 

■ 

\(-- 

idemically equal 

J 

Mrb 

right bot 

Ss 

\r- 

approx ™ 

\ 

Mlk 

left center of big curly bracket 

— 

\(ap 

approximates 

\ 

Mrk 

right center of big curly bracket 


\(!- 

not equal 

1 

Mbv 

bold vertical 

— 

\(-> 

right arrow 

l. 

\0f 

left floor (left bottom of big 

• — 

\«- 

left arrow 



square bracket) 

1 

\(ua 

up arrow 

J 

Mrf 

right floor (right bottom) 

1 

\(da 

down arrow 

f 

MIc 

left ceiling (left top) 

X 

\(mu 

multiply 

1 

Mrc 

right ceiling (right top) 


tMapped into uppercase English letters in the font mounted on font position one. 
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CHARACTER SIZE CONTROL REQUESTS 


REQUEST 

FORM 

INITIAL 

VALUE 

IF NO 

ARGUMENT 

EXPLANATION 

.cs F N M 

off 


Set constant character space (width) mode on for font F(if 
mounted). The width of every character is assumed to be 
iV/36 ems. If iW is absent, the em is that of the character 
point size; if M is given, the em is M points. All affected 
characters are centered in this space including those with 
an actual width larger than this space. Special font charac¬ 
ters occurring while the current font is F are also so 
treated. If N is absent, the mode is turned off. The mode 
must still (or again) be in effect when the characters are 
printed. There is no effect in the nroff formatter. 

.ps ±N 

10 point 

previous 

Set point size to ±N. Any positive size value may be re¬ 
quested; if invalid, the next larger valid size will result 
(maximum of 36). A paired sequence +N, -N will work 
because the previous requested value is remembered. For 
point size changes within a line of text, sequences \s N or 
\s±N can be used. Relevant parameters are a part of the 
current environment. There is no effect in the nroff format¬ 
ter. 

.ss N 

12/36 em 

ignored 

Set space-character size to N/ 36 ems. This size is the mini¬ 
mum word spacing in adjusted text. Relevant parameters 
are a part of the current environment. Thre is no effect in 
the nroff formatter. 
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PAGE CONTROL REQUESTS 


REQUEST 

FORM 

INITIAL 

value* 

IF NO 

ARGUMENT 

EXPLANATION 

.bp ±N 

N -1 


Begin page. The current page is ejected and a new page is 
begin. If ±N is given, the new page number will be ±N. The 
page number indicator ( N) is ignored if not specified in the 
request. The request causes a break. The use of ” as the 
control character (instead of “.”) suppresses the break 
function. The request with no N is inhibited by the .ns 
request. 

.mk R 

none 

internal 

Mark current vertical place in an internal register (associ¬ 
ated with the current diversion level) or in register R, if 
given. The request is used in conjunction with “return to 
marked vertical place in current diversion” request (.rt). 
Mode or relevant parameters are associated with current 
diversion level. 

.ne N 


JV-1V 

Need N vertical spaces. The vertical space indicator (N) is 
ignored if not specified in the request. 

• If the distance to the next trap position (D) is less 
than N, a forward vertical space of size D occurs 
which will spring the trap. 

• If there are no remaining traps on the page, D is the 
distance to the bottom of the page. 

• If D is less than vertical spacing (V), another line 
could still be output and spring the trap. 

In a diversion, D is the distance to the diversion trap (if 
any) or is very large. Mode or relevant parameters are asso¬ 
ciated with current diversion level. 

.pi ±N 

llin 

llin 

Page length set to ±N. The internal limitation is about 75 
inches in the troff formatter and 136 inches in the nroff 
formatter. Current page length is available in the .p regis¬ 
ter. The page length indicator (N) is ignored if not speci¬ 
fied in the request. 

.pn ±N 

N—l 

ignored 

Page number. The next page (when it occurs) will have the 
page number ±N. The request must occur before the initial 
pseudopage transition to affect the page number of the 
first page. The current page number is in the % register. 


•Values separated by are for the nroff and troff formatters, respectively. 
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TABLE 3.F (Con'd) 


PAGE CONTROL REQUESTS 


REQUEST 

FORM 

INITIAL 

VALUE* 

IF NO 

ARGUMENT 

EXPLANATION 

.po ±N 

0; 

26/27in 

previous 

Page offset. The current left margin is set to ±N. The page 
offset indicator (N) is ignored if not specified in the re¬ 
quest. The troff formatter initial value provides about 1 
inch of paper margin including the physical typesetter 
margin of 1/27 inch. In the troff formatter, the maximum 
(line-length) + (page-offset) is about 7.54 inches. The cur¬ 
rent page offset is available in the .o register. 

.rt ±N 

none 

internal 

Return (upward only) to marked vertical place in current 
diversion. If ±JV(with respect to place) is given, the verti¬ 
cal place is ±N from the top of the page or diversion. If N is 
absent, the vertical place is marked by a previous .mk. The 
.sp request may be used in all cases instead of .rt by spacing 
to the absolute place stored in an explicit register; e.g., 
using the sequence .mk R ... .*p/\nJRu. Mode or relevant 
parameters are associated with current diversion level. 


•Values separated by are for the nroff and troff formatters, respectively. 
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TEXT FILLING, ADJUSTING, AND CENTERING REQUESTS 


REQUEST 

FORM 

INITIAL 

VALUE 

IF NO 

ARGUMENT 

EXPLANATION 

.ad N 

adjust 

adjust 

Adjust. Output lines are adjusted with mode N. If the type 
indicator ( N) is present, the adjustment type is as follows: 

N ADJUSTMENT TYPE 

1 adjust left margin only 

r adjust right margin only 

c center 

b or n adjust both margins 

absent unchanged 

The adjustment type indicator N may also be a number 
obtained from the .j register. If fill mode is not on, adjust¬ 
ment will be deferred. Relevant parameters are a part of 
the current environment. 

.br 



Break. Filling of the line currently being collected is 
stopped, and the line is output without adjustment. Text 
lines beginning with space characters and empty text lines 
(blank lines) also cause a break. 

.ce N 

off 

JV=1 

Center. The next N input text lines are centered within the 
current line-length. If N= 0, any residual count is cleared. 

A break occurs after each of the AT input lines. If the input 
line is too long, it will be left adjusted. The request nor¬ 
mally causes a break. Relevant parameters are a part of 
the current environment. 

.fi 

fill 

— 

Fill mode. The request causes a break. Subsequent output 
lines are filled to provide an even right margin. Relevant 
parameters are a part of the current environment. 

.na 

adjust 


No adjust No output line adjusting is done. Since adjust¬ 
ment is turned off, the right magin will be ragged. Adjust¬ 
ment type for the .ad request is not changed. Output line 
filling still occurs if fill mode is on. Relevant parameters 
are a part of the current environment. 

.nf 

fill 


No-fill mode. Subsequent output lines are neither filled nor 
adjusted. The request normally causes a break. Input text 
lines are copied directly to output lines without regard for 
the current line length. Relevant parameters are a part of 
the current environment. 
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VERTICAL SPACING REQUESTS 


REQUEST 

FORM 

INITIAL 

VALUE* 

IF NO 

ARGUMENT 

EXPLANATION 

.Is JV 

JV-1 

previous 

Line spacing set to ±N. Output JV-1 blank lines (Vs) after 
each output text line. If the text or previous appended 
blank line reached a trap position, appended blank lines are 
omitted. Relevant parameters are a part of the current 
environment. 

.ns 

space 

• 

Set no*space mode on. The no-space mode inhibits .sp and 
.bp requests without a next page number. It is turned off 
when a line of output occurs or with the .rs request. Mode or 
relevant parameters are associated with current diversion 
level. 

.os 

— 

— 

Output saved vertical space. The request is used to output a 
block of vertical space requested by an earlier .*v request. 
The no-space mode has no effect. 

.rs 

— 

— 

Restore spacing. The no-space mode is turned off. Mode or 
relevant parameters are associated with current diversion 
level. 

.sp JV 


JV- IV 

Space vertically. The request provides spaces in either di¬ 
rection. If JV is negative, the motion is backward (upward) 
and is limited to the distance to the top of the page. For¬ 
ward (downward) motion is truncated to the distance to the 
nearest trap. The space indicator (JV) is ignored if not spec¬ 
ified in the request. If the no-space mode is on, no spacing 
occurs (see .ns and .rs). The request causes a break. 

.sv JV 


JV= IV 

Save a contiguous vertical block of size JV. If the distance to 
the next trap is greater than N, JV vertical spaces are out¬ 
put. If the distance to the next trap is less than N, no 
vertical space is immediately output: but JV is remembered 
for later output (see .os). Subsequent .sv requests overwrite 
any still remembered JV. No-space mode has no effect The 
vertical block size indicator (JV) is ignored if not specified. 

.vs JV 

l/6in; 

12pts 

previous 

Set vertical base-line spacing size V. Transient extra verti¬ 
cal spaces are available with \ x’JV. The vertical base-line 
spacing indicator (JV) is ignored if not specified in the re¬ 
quest. Relevant parameters are a part of the current envi¬ 
ronment. 

Blank line 

— 

— 

This condition causes a break and output of a blank line 
(just as does .sp 1). 


•Values separated by are for the nroff and troff formatters, respectively. 
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UNE LENGTH AND INDENTING REQUESTS 


REQUEST 

FORM 

INITIAL 

VALUE 

IF NO 

ARGUMENT 

EXPLANATION 

•in ±N 

N= 0 

previous 

Indent. The indent is set to ±N and prepended to each 
output line. Indent indicator (IV) is ignored if not specified 
by the request. Relevant parameters are a part of the cur¬ 
rent environment. The request causes a break. 

.11 ±1 V 

6.5 in 

previous 

Line length. The line length is set to ±N. In the troff for¬ 
matter, the maximum (line-length) + (page-offset) is about 
7.54 inches. The line length indicator ( N) is ignored if not 
specified in the request. Relevant parameters are a part of 
the current environment. 

•ti ±N 


ignored 

Temporary indent. The next output text line will be in¬ 
dented a distance ±N with respect to the current indent. 
The resulting total indent may not be negative. The current 
indent is not changed. The indent indicator (IV) is ignored 
if not specified in the request. Relevant parameters are a 
part of the current environment. The request causes a 
break. 
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TABLE 3.J 


MACROS, STRINGS, DIVERSIONS, AND POSITION TRAPS REQUESTS 


REQUEST 

FORM 

INITIAL 

VALUE 

IF NO 

ARGUMENT 

EXPLANATION 

.am xx yy 

— 

.yy*.. 

Append to macro xx (append version of .de). 

.as xx string 


ignored 

Append string to string xx (append version of .d*). 

.ch xx N 



Change trap location. Change the trap position for macro 
xx to be N. In the absence of N, the trap, if any, is re¬ 
moved. The trap location indicator (!V) is ignored if not 
specified in the request. 

.da xx 


end 

Divert and append to macro xx (append version of the .di 
request). Mode or relevant parameters are associated with 
current diversion level. 

.de xx yy 


•yy-.. 

Define or redefine macro xx The contents of the macro 
begin on the next input line. Input lines are copied in copy 
mode until the definition is terminated by a line beginning 
with .yy. The macro yy is then called. In the absence of yy, 
the definition is terminated by a line beginning with A 

macro may contain .d« requests provided the terminating 
macros differ or the contained definition terminator is con¬ 
cealed; can be concealed as “ \\.” which will copy as 

and be reread as 

.di xx 


end 

Divert output to macro xx Normal text processing occurs 
during diversion except that page offsetting is not done. 
The diversion ends when the request .di or .da is encoun¬ 
tered without an argument; extraneous requests of this 
type should not appear when nested diversions are being 
used. Mode or relevant parameters are associated with cur¬ 
rent diversion level. 

.ds xx string 

— 

ignored 

Define a string xx containing string. Any initial double¬ 
quote in string is stripped to permit initial blanks. 

.dt N xx 


off 

Install a diversion trap at position N in the current diver¬ 
sion to invoke macro xx Another .dt will redefine the div¬ 
ersion trap. If no arguments are given, the diversion trap is 
removed. Mode or relevant parameters are associated with 
current diversion level. 

.em xx 

none 

none 

End macro. Macro xx will be invoked when all input has 
ended. The effect is the same as if the contents of xx had 
been at the end of the last file processed. 
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TABLE 3.J (Contd) 

MACROS, STRINGS, DIVERSIONS, AND POSITION TRAPS REQUESTS 


REQUEST 

FORM 

INITIAL 

VALUC 

IF NO 

ARGUMENT 

EXPLANATION 

.it N xx 


off 

Input-line-count trap. An input-line-count trap is set to 
invoke the macro xx after N lines of text input have been 
read (control or request lines do not count). Text may be in¬ 
line or interpolated by in-line or trap-invoked macros. Rel¬ 
evant parameters are a part of the current environment. 

.rm xx 

— 

ignored 

Remove. A request, macro, or string is removed. The name 
xx is removed from the name list and any related storage 
space is freed. Subsequent references have no effect. 

.rn xx yy 


ignored 

Rename. Rename request, macro, or string from xxto yy. 

If yy exists, it is first removed. 

.wh N xx 



When. A location trap is set to invoke xx at page position 

N, a negative N is interpreted with respect to the page 
bottom. Any macro previously planted at AT is replaced by 
xx A zero N refers to the top of a page. In the absence of 
xx, the first found trap at JV, if any, is removed. The page 
position indicator (JV) is ignored if not specified in the re¬ 
quest 
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PREDEFINED GENERAL NUMBER REGISTERS 


REGISTOt 

NAME 

DESCRIPTION 

% 

Current page number. 

Ct 

Character type (set by width function). 

dl 

Width (maximum) of last completed diversion. 

dn 

Height (vertical size) of last completed diversion. 

dw 

Current day of the week (1 through 7). 

dy 

Current day of the month (1 through 31). 

hp 

Current horizontal place on input line. 

In 

Output line number. 

mo 

Current month (1 through 12). 

nl 

Vertical position of last printed text base line. 

sb 

Depth of string below base line (generated by width function). 

St 

Height of string above base line (generated by width function). 

yr 

Last two digits of current year. 

c. 

Provides general register access to the input line number in the current input file. 
Contains the same value as the read-only .c register. 

.R 

Number of number registers that remain, available for use. 

.b 

Emboldening factor of the current font 
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TABLE 3.L 

PREDEFINED READ-ONLY NUMBER REGISTERS 


REGISTER 

NAME 

DESCRIPTION 

.$ 

Number of arguments available at the current macro level. 

.A 

Set to 1 in the troff formatter if -a option used; always 1 in the nroff 
formatter. 

.F 

Value is a string that is the name of the current input file. 

.H 

Available horizontal resolution in basic units. 

.L 

Contains the current line spacing parameter (the value of the most 
recent .1* request). 

.P 

Contains the value 1 if the current page is being printed and the 
value 0 if the current page is not in the -o option list. 

.T 

Set to 1 in the nroff formatter if -T option used; always 0 in the troff 
formatter. 

.V 

Available vertical resolution in basic units. 

.a 

Post-line extra line space most recently utilized using x’N. 

•C 

Number of lines read from current input Hie. 

.d 

Current vertical place in current diverson; equal to nl if no diversion. 

.f 

Current font as physical quadrant (1 through 4). 

.h 

Text base-line high-water mark on current page or diversion. 

.i 

Current ident 

0 

Indicates the current adjustment mode and type. Can be saved and 
later given to the .ad request to restore a previous mode. 

.k 

Contains the horizontal size of the text portion (without ident) of the 
current partially collected output line, if any, in the current environ¬ 
ment. 

.1 

Current line length. 

.n 

Length of text portion on previous output line. 

.0 

Current page offset. 

•P 

Current page length. 

.s 

Current point size. 

.t 

Distance to the next trap. 

•U 

Equal to 1 in fill mode and 0 in no-fill mode. 

.V 

Current vertical line spacing. 

.w 

Width of previous character. 

•X 

Reserved version-dependent register. 

•y 

Reserved version-dependent register. 

.Z 

Name of current diversion. 
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TABLE 3.M 

NUMBER REGISTERS REQUESTS 


REQUEST 

FORM 

INITIAL 

VALUI 

IP NO 

ARGUMENT 

EXPLANATION 

.af Re 

arabic 


Assign format Format cis assigned to register R Avail¬ 
able formats are: 

c NUMBERING SEQUENCE 

1 0,1,2,3,4,5,... 

001 000,001,002,003,004,005,... 

i 0,i,ii,iii,iv,v,... 

I o,i,ii,iii,rv,v,... 

a 0 ,a,b,...^,aa,ab,...,z 2 ,aaa,... 

A 0,A,B,...,Z,AA,AB,...,ZZ,AAA,... 

An arabic format having JVdigits specifies a Held width of 

N digits. Read-only registers and width function are al¬ 
ways arabic. 

.nr R+NM 


• 

Number register. The number register R is assigned the 
value +JV with respect to the previous value, if any. The 
automatic incrementing value is set to M. The number 
register value (IV) is ignored if not specified in the request 

.rr R 



Remove register. The number register R is removed. If 
many registers are being created dynamically, it may be 
necessary to remove registers that are no longer used in 
order to recapture internal storage space for newer regis¬ 
ters. 
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TABS, LEADERS, AND FIELDS REQUESTS 


REQUEST 

FORM 

INITIAL 

VALUE* 

IF NO 

ARGUMENT 

EXPLANATION 

.fc a b 

off 

Off 

Field delimiter is set to a. The padding indicator is set to 
the space character or to b, if given. In the absence of 
arguments, the field mechanism is turned off. 

.lc C 

• 

non? 

Leader repetition character becomes c or is removed spec¬ 
ifying motion. Relevant parameters are a part of the cur¬ 
rent environment. 

.ta Nt.. 

8n; 0.5 in 

none 

Set tab stops and types. 

When the tab type indicator (t) is: 

R — text is right adjusted 

C — text is centered 

Absent — text is left adjusted. 

Tab stops for the troff formatter are preset every 0.5 inch; 
tab stops for the nroff formatter are preset every eight 
nominal character widths. Stop values are separated by 
spaces, and a value preceded by + is treated as an incre¬ 
ment to the previous stop value. Relevant parameters are 
a part of current environment. 

.tc c 

none 

none 

Tab repetition character becomes cor is removed specify¬ 
ing motion. Relevant parameters are a part of the current 
environment. 


•Values separated by are for the nroff and troff formatters, respectively. 
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TABLE 3.0 


INPUT AND OUTPUT CONVENTIONS AND CHARACTER TRANSLATIONS REQUESTS 


REQUEST 

FORM 

INITIAL 

VALUE* 

IF NO 

ARGUMENT 

EXPLANATION 

.cc c 

• 

• 

Set control character to cor reset to Relevant parame¬ 

ters are a part of the current environment. 

.cu N 

off 

JV= 1 

Continuous underline in the nroff formatter. A variant of 
.ul that causes every character to be underlined. Identical 
to .ul in the troff formatter. Relevant parameters are a 
part of the current environment. 

.c2 c 

» 

9 

Set no-break control character to c or reset to Rele¬ 

vant parameters are a part of the current environment. 

.ec c 

\ 

\ 

Set escape character to \ or to c, if given. 

.eo 

on 

— 

Turn escape character mechanism off. 

•lg N 

of;on 

on 

Ligature mode is turned on if N is absent or nonzero and 
turned off if JV=0. If N=2, only the 2-character ligatures 
are automatically invoked. Ligature mode is inhibited for 
request, macro, string, register, file names, and copy 
mode. There is no effect in the nroff formatter. 

,tr abed.... 

none 


Translate a into b, c into d, etc. on output. If an odd 
number of characters is given, the last one will be mapped 
into the space character. To be consistent, a particular 
translation must stay in effect from input to output time. 
Initially, there are no translate values. 

.uf F 

Italic 

Italic 

Underline font set to F (to be switched to by .ul). In the 
nroff formatter, Fmay not be on position 1 (initially Times 
Roman). 

.ul N 

off 

N=l 

Underline in the nroff formatter (italicize in troff the nex* 

N input text lines). Switch to underline font saving the 
current font for later restoration; other font changes 
within the span of a .ul will take effect, but the restoration 
will undo the last change. Output generated by a .tl is 
affected by the font change but does not decrement N. If 

N is greater than 1, there is the risk that a trap interpo¬ 
lated macro may provide text lines within the span, which 
environment switching can prevent. Relevant parameters 
are a part of the current environment. 


•Values separated by are for the nroff and troff formatters, respectively. 
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TABLE 3.P 
LOCAL MOTIONS 
VERTICAL LOCAL MOTION 


FUNCTION 

EFFECT IN 

TROFF 

NROFF 

\ \’N 
\ u 
\ d 
\r 

Move distance N 
1/2 em up 

1/2 em down 

1 em up 

1/2 line up 

1/2 line down 

1 line up 


HORIZONTAL LOCAL MOTION 



EFFECT IN 

FUNCTION 

TROFF 

NROFF 

\h’JV 

Move distance N 


\ (space) 

Unpaddable space-size space 

\0 

Digit-size space 


\ 1 

1/6 em space 

ignored 

\ A 

1/12 em space 

ignored 
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TABLE 3.Q 


HYPHENATION REQUESTS 


REQUEST 

FORM 

INITIAL 

VALUE 

IP NO 

ARGUMENT 

EXPLANATION 

.he C 

\% 

\% 

Hyphenation character. Hyphenation indicator character 
is set to c or to the default \%. The indicator does not 
appear in the output. Relevant parameters are a part of 
the current environment. 

.hw word 1~ 


ignored 

Exception words. Hyphenation points in words are speci¬ 
fied with imbedded minus signs. Versions of a word that 
end with an s are implied; i.e., dig-it implies dig-its. This 
list is examined initially and after each suffix stripping. 
Space available is small—about 128 characters. 

.hy N 

off, N= 0 

on, JV=*1 

Hyphenate. Automatic hyphenation is turned on for -V 
greater than or equal to 1 or off for N= 0. If N= 2, last lines 
(ones that will cause a trap) are not hyphenated. For JV-4 
and IV-8, the last and first two characters, respectively, of 
a word are not divided. These values are additive; i.e., 
IV-14 invokes all three restrictions. Relevant parameters 
are a part of the current environment. 

.nh 

no hyphen 

— 

No hyphenation. Automatic hyphenation is turned off. 
Relevant parameters are a part of the current environ¬ 
ment. 
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TABLE 3.R 


THREE-PART TITLES REQUEST 


REQUEST 

FORM 

INITIAL 

VALUE 

IF NO 

ARGUMENT 

EXPLANATION 

.It ±N 

6.5 in 

previous 

Length of title set to ±N. Line length and title length are 
independent. Indents do not apply to titles; page offsets 
do. Relevant parameters are a part of the current environ¬ 
ment. 

.pc c 

% 

off 

Page number character set to c or removed. The page 
number register remains %. 

.tl ’ left’center’right’ 


Three-part title. The strings left, center, and right are, 
respectively, left adjusted, centered, and right adjusted in 
the current title length. Any of the strings may be empty, 
and overlapping is permitted. If the page number charac¬ 
ter (initially %) is found within any of the fields, it is 
replaced by the current page number having the format 
assigned to register %. Any character may be used as the 
string delimiter. 




Page 150 








6/82 


ISSUE 1 


DOCUMENT PROCESSING GUIDE 


TABLE 3.S 


OUTPUT UNE NUMBERING REQUESTS 


REQUEST 

FORM 

INITIAL 

VALUE 

IF NO 

ARGUMENT 

EXPLANATION 

.nra ±N MSI 


off 

Line number mode. If ±N is given, line numbering is 
turned on; and the next output line is numbered ±N. De¬ 
fault values are 1. S=l, and 0. Parameters corre¬ 

sponding to missing arguments are unaffected; a nonnu- 
meric argument is considered missing. In the absence of 
all arguments, numbering is turned off, and the next line 
number is preserved for possible further use in number 
register In. Relevant parameters are a part of the current 
environment. 

.nn N 

— 

1 

Next iVlines are not numbered. Relevant parameters are a 
part of the current environment. 
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TABLE 3.T 

CONDITIONAL ACCEPTANCE OF INPUT REQUESTS 


REQUEST INITIAL 

FORM VALUE 

IF NO 

ARGUMENT 

EXPLANATION 

.el anything 


The “else” portion of “if-else”. 

.ie c anything 

— 

The “if’ portion of “if-else”. The ccan be any of the forms 
acceptable with the .H request. 

.if c anything 


If condition c true, accept anything as input; for multi- 
line case, use \\anything\\. 

.if !c anything 

— 

If condition c false, accept anything. 

.if N anything 

— 

If expression N greater than 0, accept anything. 

.if \N anything 

— 

If expression N less than or equal to 0, accept anything. 

.if ’stringl' string2’ anything 

If string 1 is identical to string 2 accept anything. 

.if string 1 ’ string2’ anything 

If string 1 is not identical'to string 2 accept anything. 


TABLE 3.U 


ENVIRONMENT SWITCHING REQUEST 


REQUEST 

FORM 

INITIAL 

VALUE 

IF NO 

ARGUMENT 

EXPLANATION 

.ev N 

N= 0 

previous 

Environment switched to 0, 1, or 2. Switching is done in 
pushdown fashion so that restoring a previous environ¬ 
ment must be done with .ev rather than specific reference. 
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TABLE 3.V 


INSERTIONS FROM STANDARD INPUT REQUESTS 


REQUEST 

FORM 

INITIAL 

VALUC 

IF NO 

ARGUMENT 

EXPLANATION 

.ex 

— 

— 

Exit from the nroff/troff formatter. Text processing is ter¬ 
minated exactly as if all input had ended. 

.rd prompt 


prompt-BEL 

Read insertion from the standard input until two newline 
characters in a row are found. If standard input is the user 
keyboard, a prompt (or a BEL) is written onto the user 
terminal. The request behaves like a macro; arguments 
may be placed after prompt 


TABLE 3.W 


INPUT/OUTPUT FILE SWITCHING REQUESTS 


REQUEST 

FORM 

IF NO 

ARGUMENT 

EXPLANATION 

.nx filename 

end-of-file 

Next file is filename. The current file is considered ended, and 

the input is immediately switched to file - 

name. 

.pi program 

—- 

Pipe output to program (nroff formatter only). This request must 
occur before any printing occurs. No arguments are transmitted to 
program. 

.so filename 


Switch source file (pushdown). The top input level (file reading) is 
switched to filename. Contents are intepolated at the point the 
request is encountered. When the new file ends, input is again 
taken from the original file. The .to requests may be nested. 
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TABLE 3.X 


MISCELLANEOUS REQUESTS 


REQUEST 

FORM 

INITIAL 

VALUE 

IF NO 

ARGUMENT 

EXPLANATION 

.CO 



Specify the point in the macro file at which compaction 
ends. When -kname is called on the command line, all 
lines in the file name before the .co request will be com¬ 
pacted. 

.fl 

— 

— 

Flush output buffer. Used in interactive debugging to 
force output. The request causes a break. 

•ig yy 

— 

.yy*.. 

Ignore input lines until call of yy. This request behaves 
like the .d* request except that the input is discarded. The 
input is read in copy mode, and any automatically incre¬ 
mented registers will be affected. 

.me c N 


off 

Sets margin character c and separation N. Specifies that 
a margin character c appear a distance N to the right of 
the right margin after each nonempty text line (except 
those produced by .tl). If the output line is too long (as can 
happen in no-fill mode), the character will be appended to 
the line. If N is not given, the previous N is used; the 
initial N is 0.2 inches in the nroff formatter and 1 em in 
troff. Relevant parameters are a part of the current envi¬ 
ronment. 

.pm t 


all 

Print macros. The names and sizes of all defined macros 
and strings are printed on the user terminal. If t is given, 
only the total of the sizes is printed. Sizes are given in 
blocks of 128 characters. 

.tm string 


newline 

Print string on terminal (UNIX operating system stan¬ 
dard message output). After skipping initial blanks, string 
(rest of the line) is read in copy mode and written on the 
user terminal. 


TABLE 3.Y 


OUTPUT AND ERROR MESSAGES REQUEST 


REQUEST 

FORM 

INITIAL 

VALUE 

IF NO 

ARGUMENT 

EXPLANATION 

.ab text 

' 


Prints text on the message output and terminates with¬ 
out further processing. If text is missing, “User Abort.” is 
printed. This request does not cause a break. The output 
buffer is flushed. 
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TABLE 3.Z 

NAMING CONVENTION FOR THE 
MATHEMATICS TYPESETTING PROGRAM 


CHARACTER 

i SEQUENCE 

i 

OUTPUT 

1 

; > = 

i 

i < = 

£ 

i = — 

* 

i t = 

• 

> 

i -f - 


i 


! - > 

—> 

! <- 


1 <<: 

« 

>> 

>> 

inf 

ac 

partial 

d 

half 

Vi 

prime 

1 

approx 

nothing 


cdot 

• 

times 

X 

del 

V 

grad 

V 

»■•••* 

f ... f 

sum 

V 


int 

f 

prod 

J 

n 

union 

u 

inter 

1 

| 

n 

i 


INPUT 

NAME 

CHARACTER 

DELTA 

A 

GAMMA 

r 

LAMBDA 

A 

OMEGA 

fi 

PHI 

4> 

PI 

n 

PSI 

* 

SIGMA 

2 

THETA 

e 

UPSILON 

T 

XI 


alpha 

a 

beta 

0 

chi 

X 

delta 

6 

epsilon 

c 

eta 

V 

gamma 

y 

iota 

i 

kappa 

X 

lambda 

X 

mu 

M 

nu 

V 

omega 

0) 

omicron 

0 

phi 

<t> 

Pi 

V 

psi 

+ 

rho 

p 

sigma 

a 

tau 

7 

theta 

6 

upsilon 

V 

xi 

i 

zeta 

r 
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IV. MEMORANDUM MACROS 
1. Introduction 

1.1 Purpose 

This section is a guide and reference manual for users of Memorandum Macros (MM). These macros Drovide 
a general purpose package of text formatting macros for use with the UNIX operating system text formatters 
nrof and .roff (refer ,o troffU) m the W, Man-al-UNIX Operating SvZn tor more deuiS A retere“?e 
of the form name(N) points to page name in section JTol the User's Manual. 

1.2 Conventions 

Each part of this section explains a single facility of MM. In general, the earlier a part occurs, the more 

are acStfh? m T f ° rmatl0n 19 J 0r most users - Some of the ^er parts can be completely i^ored if MM defaults 

f j Likewise, each part progresses from general case to special-case facilities. It is recommended 

then a ? a ?H detai * ? n y t0 the 1,01 where there is enough informa tion to obtain the desired format, 
then skim the rest of the part because some details may be of use to only a few. 

is paragraph [q* 1 fa C “ rly braCket3 (,,) refer *° "umbers within this saction. For example, this 

Flir™. h ,' ?T PSe . S Of'macro calls, square brackets ((J) surrounding an argument indicate that it is optional. 
Ellipses (-.) show that the preceding argument may appear more than once. 

, FigUre 4 ' 1 show u s *>£ “ ro u ff and ‘ roff formatter outputs (of files using MM macros) for a simple letter 

“1 ° f th ® tW ° formatters is obviously different, the nroff formatter output 

is described first with the troff formatter output following in parentheses. For example: 

The title is underlined (italic). 

means that the title is underlined by the nroff formatter and italicized by the troff formatter. 

1.3 Document Structure 

anv 3 d0CU K ment b f ^matted with the MM text formatting macro package has four major segments, 

any of which may be omitted; if present, the segments must occur in the following order 

• Parameter setting segment sets the general style and appearance of a document. The user can control 
page width, margin justification, numbering styles for heading and lists, page headers and footers 19} 
and many other properties of the document Also, the user can add macros or redefine existing ones 
This segment can be omitted entirely if the user is satisfied with default values; it produces no actual 
output, but performs only the formatter setup for the rest of the document. 

• Beginning segment includes those items that occur only once, at the beginning of a document, e.g. title 

author s name, date. * ’ ’ 

. Body segment Sis the actual text of the document. It may be as small as a single paragraph or as lar^e 
as hundreds of pages. It may have a hierarchy of headings up to seven levels deep {4}. Headings are auto¬ 
matically numbered (if desired) and can be saved to generate the table of contents. Five additional levels 
of subordination are provided by a set of list macros for automatic numbering, alphabetic sequencing 

erenc^ a an 1 d^ootnote3 t |7™8^li|^ e ^ ^ ^ Vari ° US tyP ' S displays ’ table5 ' figures - ref ' 

• Ending segment contains those items that occur only once at the end of a document. Included are signa¬ 
ture^) and lists of notations (e.g., “Copy to” lists) {6.11}. Certain macros may be invoked here to print 
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information that is wholly or partially derived from the rest of the document, such as the table of con¬ 
tents or the cover sheet for a document {10}. 

Existence and size of these four segments varies widely among different document types. Although a spe¬ 
cific item (such as date, title, author names, etc.) may differ depending on the document, there is a uniform way 
of typing it into an input text file. 

1 .4 Input Text Structure 

In order to make it easy to edit or revise input file text at a later time. 

• Input lines should be kept short 

• Lines should be broken at the end of clauses 

• Each new sentence should begin on a new line. 

1.5 Definition* 

Formatter refers to either the nroff or troff text-formatting program. 

Requests are built-in commands recognized by the formatters. Although a user seldom needs to use these 
requests directly {3.10}, this section contains references to some of the requests. For example, the request 

.sp 

inserts a blank line in the output at the place the request occurs in the input text file. 

Macros are named collections of requests. Each macro is an abbreviation for a collection of requests that 
would otherwise require repetition. The MM package supplies many macros, and the user can define additional 
ones. Macros and requests share the same set of names and are used in the same way. 

Table 4.A is an alphabetical list of macro names used by MM. The first line of each item lists the name of 
the macro, a brief description, and a reference to the paragraph in which the macro is described. The second 
•line illustrates a typical call of the macro. 

Strings provide character variables, each of which names a string of characters. Strings are often used 
in page headers, page footers, and lists. These registers share the pool of names used by requests and macros. 
A string can be given a value via the .ds (define string) request; and its value can be obtained by referencing 
its name, preceded by “\*” (for 1-character names) or ‘VC (for 2-character names). For instance, the string 
DT in MM normally contains the current date, thus the input line 

Today is \*(DT. 

may result in the following output 

Today is December 16,1981. 

The current date can be replaced, e.g.: 

.ds DT 01/01/79 

by invoking a macro designed for that purpose {6.8}. Table 4.B is an alphabetical list of string names used by 
MM. A brief description, paragraph reference, and initial (default) value(s) are given for each. 
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Number registers fill the role of integer variables. These registers are used for flags and for arithmeti 
and automatic numbering. A register can be given a value using a .nr request and be referenced by preeedini 
its name by \n (for 1-character names) or \n( (for 2-character names). For example, the following sets the valu 
of the register d to one more than that of the register dd : 

.nr d l+\n(dd 

Table 4.C is an alphabetical list of number register names giving for each a brief description, paragraph refer¬ 
ence, initial (default) value, and legal range of values (where (m:n) means values from m to n, inclusive. 

Paragraph 14.1 contains naming conventions for requests, macros, strings, and number registers. Table 4JL, 
4.B, and 4.C list all macros, strings, and number registers defined in MM. 

2. Usag* 

This part describes how to access MM, illustrates UNIX operating system command lines appropriate for 
various output devices, and describes command line flags for the MM text formatting macro package. 

2.1 Th# mm Command 


The mm(l) command can be used to prepare documents using the nroff formatter and MM; this command 
invokes nroff with the -cm flag {2 2). The mm command has options to specify preprocessing by tbl and/or 
by neqn and for postprocessing by various output filters. Any arguments or flags that are not recognized by 
the mm command, e.g., -rC3, are passed to the nroff formatter or to MM, as appropriate. Options, which eai 
occur in any order but must appear before the file names, are: 


option 


-e 


-t 


-c 


-E 

-y 

-12 


MEAMMO 

The neqn is to be invoked; also causes neqn to read /usr/pub/eqnchar [see eqncharfT)] 
The tbl(l)is to be invoked. 

The col(l)is to be invoked. 

The -e option of the nroff formatter is to be invoked. 

The -mm (uncompacted macros) is to be used instead of -cm. 

The 12-pitch mode is to be used. The pitch switch on the terminal should be set to 12 if nec¬ 
essary. 


-T450 Output is to a DASI450. This is the default terminal type [unless $TERM is set; see sh(l)]. 

It is also equivalent to -T1620. 

-T450-12 Output is to a DASI 450 in 12-pitch mode. 

~T300 Output is to a DASI 300 terminal. 

-T300-12 Output is to a DASI 300 in 12-pitch mode. 

-T300s Output is to a DASI 300S. 

-T300s-12 Output is to a DASI 300S in 12-pitch mode. 

-T4014 Output is to a Tektronix 4014. 
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OPTION 

-T37 

Output is 

-T382 

Output is 

-T4000a 

Output is 

-TX 

Output is 

-Thp 

Output is 

-T43 

Output is 

-T40/4 

Output is 

-T745 

Output is 

-T2631 

Output is 

-Tip 

expanded 

Output is 


plies -c). 


MEANING 


Any other -T option given does not produce an error, it is equivalent to -Tip. 

A similar command is available for use with the troff formatter [ mmt(l)]. 
2.2 The —cm or —mm Flog 


The MM package can also be invoked by including the -cm or -mm flag as an argument to the formatter. 
The -cm flag causes the precompacted version of the macros to be loaded. The -mm flag causes the file 
/usr/lib/tmac/lmacm to be read and processed before any other files. This action defines the MM macros, sets 
default values for various parameters, and initializes the formatter to be ready to process the input text files. 

2.3 Typical Command linos 


The prototype command lines 


are as follows (with the various 


options explained in {2.4}): 


o Text without tables or equations: 


mm {options) file ... 
or 

nroff [options] —cm file ... 

mint (options] file ... 
or 

troff [options] —cm file ... 
o Text with tables: 


mm -t [options] file ... 
or 

tbl file ... I nroff [options] -cm 
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mint -t [options] file ... 
or 

tbl Hie ... I troff [options] -cm 

• Text with equations: 

mm -e (options] file ... 
or 

neqn /usr/pub/eqnchar file ... I nroff [options] -cm 

ramt -e [options] file ... 
or 

eqn /usr/pub/eqnchar file ... I troff [options] -cm 

• Text with both tables and equations: 

mm -t -e [options] file ... 
or 

tbl file ... 1 neqn /usr/pub/eqnchar — I nroff [options] -cm 

mmt -t -e [options] file _. 
or 

tbl file ... I eqn /usr/pub/eqnchar — 1 troff \ [options] -cm 

When formatting a document with the nroff processor, the output should nor mall y be processed for a spe¬ 
cific type of terminal because the output may require some features that are specific to a given terminal, rg, 
reverse paper motion or half-line paper motion in both directions. Some commonly used terminal types and the 
command lines appropriate for them are given below. More information is found in paragraph {2.4} of this part, 
and 300(1), 450(1), 4014(1), hp(l), col(l), termio(4), and term(5) of the User’s Manual — UNIX Operating 
System . - - ^ - 6 

• DASI 450 in 10-pitch, 6 lines/inch mode, with 0.75 inch offset, and a line length of 6 inches (60 charac¬ 
ters) where this is the default terminal type so no -T option is needed (unless $TERM is set to another 
value): 

mm file ... 
or 

nroff —T450 -h -cm file ... 

• DASI 450 in 12-pitch, 6 lines/inch mode, with 0.75 inch offset, and a line length of 6 inches (72 charac¬ 
ters): 

mm -12 file ... 
or 

nroff -T450-12 -h -cm file ... 

or to increase the line length to 80 characters and decrease the offset to 3 characters: 

mm -12 -rW80 -r03 file ... 
or 

nroff -T450-12 -rW80 -r03 -h -cm file ... 

• Hewlett-Packard HP264x CRT family, 
mm -Thp file ... 
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or 

nroff -cm file I col I hp 

• Any terminal incapable of reverse paper motion and also lacking hardware tab stops (Texas Instru¬ 
ments 700 series, etc.): 

mm -T745 file - 
or 

nroff -cm file _ I col -x 

The tbl(l) and eqml)/neqn formatters, if needed, must be invoked as shown in the command lines illus¬ 
trated earlier. 

If 2-column processing {12.4} is used with the nroff formatter, either the -c option must be specified to 
mm(l) (mm(l) uses col(l) automatically for many terminal types {2.1}) or the nroff formatter output must 
be postprocessed by col(l). In the latter case, the -T37 terminal type must be specified to the nroff formatter, 
the —h option must not be specified, and the output of cold) must be processed by the appropriate terminal 
filter [e.g., 450(1)]; mm(l) with the -c option handles all this automatically. 

2.4 Parameters Set From Command Line 

Number registers are commonly used within MM to hold parameter values that control various aspects of 
output style. Many of these values can be changed within the text files with Jir requests. In addition, some of 
these registers can be set from the command line. This is a useful feature for those parameters that should not 
be permanently embedded within the input text If used, the number registers (with the possible exception of 
the register P below) must be set on the command line (or before the MM macro definitions are processed). The 
number register meanings are: 

KEGtSTB MEANING 


—rAn n = 1 has effect of invoking the .AF macro without an argument {6.9} . 

n = 2 permits use of Bell System logo, if available, on a printing device (currently available 
for Xerox 9700 only). 

-rCn sets type of copy (e.g., DRAFT) to be printed at bottom of each page {9.2.4} . 
d = 1 for OFFICIAL FILE COPY. 
a = 2 for DATE FILE COPY. 

a = 3 for DRAFT with single spacing and default paragraph style. 
o = 4 for DRAFT with double spacing and 10-space paragraph indent. 

—rDl sets debug mode. 

This flag requests formatter to continue processing even if MM detects errors that would 
otherwise cause termination. It also includes some debugging information in the default 
page header {9.2.1,12.3}. 
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REGiSTn MEANING 

—rEo controls font of Subject/Date/From fields. 

o*0, fields are bold (default for the troff formatter). 

o*l, fields are Roman font (regular text-default for the nroff formatter). 

—rLlt sets length of physical page to k lines. 

For the nroff formatter, k is an unsealed number representing lines. 

For the troff formatter, k must be scaled. 

Default value is 66 lines per page. 

This flag is used, for example, when directing output to a Versatec* printer. 

—rNn specifies page numbering style. 

o*0 (default), all pages get the prevailing header {9.2.1} . 
o*l, page header replaces footer on page 1 only. 

0 * 2 , page header is omitted from page 1. 

o-3, "section-page" numbering {4.5} occurs (.FD {8.3} and .RP {11.4} defines 
footnote and reference numbering in sections). 

o-4, default page header is suppressed; however, a user-specified header is not affected. 
o-5, "section-page” and "section-figure" numbering occurs. 


m 

PAG! 1 

PACES 2FF. 

0 

header 

header 

1 

header replaces footer 

header 

2 

no header 

header 

3 

“section-page” as footer 

same as page 1 

4 

no header 

no header unless .PH defined 

5 

“section-page” as footer and “section-figure” 

same as page 1 


Contents of the prevailing header and footer do not depend on number register AT value; JV 
controls only whether the header (IV*3) or the footer (N=5) is printed, as well as the page 
numbering style. If header and footer are null {9.2.1, 9.2.4 } , the value of JV is irrelevant 

—rOJt offsets output k spaces to the right. 

For the nroff formatter, *is an unsealed number representing lines or character positions. 
For the troff formatter, k must be scaled. 

This flag is helpful for adjusting output positioning on some terminals. The default offset, 
if this regular is not set on the command line, is 0.75 inches. 

Note: Register name is the capital letter “0”. 

—rPn specifies that pages of the document are to be numbered starting with n. 

This register may also be set via a .nr request in the input text. 

—rSn sets point size and vertical spacing for the document. The default a is 10, i.e., 10-point type 

on 12-point vertical spacing, giving six lines per inch {12.9} . This flag applies to the troff 
formatter only. 

* Registered Trademark of Versatec, Inc. 
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MOISTS* 


MEANING 


—rTa 


—rUl 


—rWJc 


provides register settings for certain devices. 

If a is 1. line length and page offset are set to 80 and 3, respectively. 

Setting u to 2 changes the page length to 84 lines per page and inhibits underlining- it is 
meant for output sent to the Versatec printer. ing; 1118 

The default value for n is 0. 

This flag applies to the nroff formatter only. 

controls underlining of section headings. 

This flag causes only letters and digits to be underlined. Otherwise, all characters (includ¬ 
ing spaces) are underlined {4.2.2.4.2 ). «**raciers unciua- 

This flag applies to the nroff formatter only. 

sets page width (line length and title length) to It 

* 18 an unsealed number representing character positions 
For the troff formatter, k must be scaled. 

This flag can be used to change page width from the default value of 6 inches (60 charac¬ 
ters in. 10 pitch or 72 characters in 12 pitch). 1 cnarac 


2.5 Omission of -cm or —mm Flag 


If a large number of arguments is required 
(or only) input file of a document as follows: 


on the command line, it may be convenient to set up the first 


tero or more initializations of registers listed in {2.4} 
-so /usr/lib/tmac/tmac.m 
remainder of text 


In this case, the user must not use the -cm or -mm flag [nor the mm(l) or mmt(l) commandl- the .so 
request has the equivalent effect, but registers in {2.4} must be initialized before the .so request bemuse their 
values are meaningful only if set before macro definitions are processed. When using this method, it is best to 
lock into the input file only those parameters that are seldom changed. For example 

.nr W 80 
Jir O 10 
.nr N 3 

.so /usr/lib/tmac/tmac.m 
-H 1 " INTRODUCTION" 


specifies, for the nroff formatter, a line length (W) of 80. a page offset (O) of 10, and “section-page” (N) number- 

3. Formatting Concepts 
3.1 Bosk Terms 

Normal action of the formatters is to fill output lines from one or more input lines. Output lines may be 
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justified so that both the left and right margins are aligned. As lines are being filled, words may a lso be hyphen¬ 
ated {3.4) as necessary. It is possible to turn any of these modes on and off (.SA {12^}, Hy (3.4), and the jnf anc 
formatter requests). Turning off fill mode also turns off justification and hyphenation. 

Certain formatting commands (requests and macros) cause filling of the current output line to cease, the 
line (of whatever length) to be printed, and subsequent text to begin a new output line. This printing of a par¬ 
tially filled output line is known as a break A few formatter requests and most of the MM macros cause a break 

Formatter requests {3.10} can be used with MM; however, there are consequences and side effects that trh 
such request might have. A good rule is to use formatter requests only when absolutely necessary. The MM 
macros described herein should be used in most cases because: 

• It is much easier to control (and change at any later point in time) overall style of the document. 

• Complicated features (such as footnotes or tables of contents) can be obtained with ease. 

• User is insulated from peculiarities of the formatter language. 

3.2 Arguments and Double Quotes 

For any macro call, a null argument is an argument whose width is zero. Such an argument often has a spe¬ 
cial meaning; the preferred form for a null argument is " ". Omitting an argument is not the same as supplying 
a null argument (e.g., the JUT macro in {6.7}). Omitted arguments can occur only at the end of an argument 
list; null arguments can occur anywhere in the list. 

Any macro argument containing ordinary (paddable) spaces must be enclosed in double quotes. A double 
quote ('') is a single character that must not be confused with two apostrophes or acute accents (") or with two 
grave accents (''). Otherwise, it will be treated as several separate arguments. 

Double quotes are not permitted as part of the value of a macro argument or of a string that is to be used 
as a macro argument If it is necessary to have a macro argument value, two grave accents (") and/or two acute 
accents (") may be used instead. This restriction is necessary because many macro arguments are processed (in¬ 
terpreted) a variable number of times. For example, headings are first printed in the text and may be reprinted 
in the table of contents. 

3.3 UnpoddabU Spaces 

When output lines are justified to give an even right margin, existing spaces in a line may have additional 
spaces appended to them. This may distort the desired alignment of text. To avoid this distortion, it is necessary 
to specify a space that cannot be expanded during justification, i.e., an unpaddable space. There are several wavs 
to accomplish this: 

• The user may type a backslash followed by a space (\ ). This pair of characters directly generates an 
unpaddable space. 

• The user may sacrifice some seldom-used character to be translated into a space upon output. 

Because this translation occurs after justification, the chosen character may be used anywhere an unpaddable 
space is desired. The tilde (%) is often used with the translation macro for this purpose. To use the tilde in this 
way, the following is inserted at the beginning of the document 

.tr * 

If a tilde must actually appear in the output, it can be temporarily “recovered” by inserting 
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before the place where needed. Its previous usage is restored by repeating the .tr <v after a break or after the 
line containing the tilde has been forced out. 

Note: Use of the tilde in this fashion is not recommended for documents in which the tilde is used within 
equations. 

3.4 Hyphenation 

Formatters do not perform hyphenation unless requested. Hyphenation can be turned on in the body of the 
text by specifying 

.nr Hy 1 

once at the beginning of the document input file. Paragraph 8.3 describes hyphenation within footnotes and 
across pages, 

If hyphenation is requested, formatters will automatically hyphenate words if need be. However, the user 
may specify hyphenation points for a specific occurrence of any word with a special character known as a hy¬ 
phenation indicator or may specify hyphenation poipts for a small list of words (about 128 characters). 

If the hyphenation indicator (initially, the 2-character sequence “\%”) appears at the beginning of a word, 
the word is not hyphenated. Alternatively, it can be used to indicate legal hyphenation points inside a word. 
All occurrences of the hyphenation indicator disappear on output 

The user may specify a different hyphenation indicator. 

-HC [hyphenation-indicator] 

The circumflex (') is often used for this purpose by inserting the following at the beginning of a document 
input text file; 

JIC * 

Note: Any word containing hyphens or dashes (also known as em dashes) will be hyphenated immedi¬ 
ately after a hyphen or dash if it is necessary to hyphenate the word, even if the formatter hyphenation 
function is turned off. 

The user may supply, via the exception word Jjw request, a small list of words with the proper hyphenation 
points indicated. For example, to indicate the proper hyphenation of the word “printout”, the user may specify 

.hw print-out 


3.5 Tabs 

Macros .MT {6.7}, .TC {10.1}, and .CS {10.2} use the formatter tabs .ta request to set tab stops and then re¬ 
store the default values of tab settings (every eight characters in the nroff formatter; every V4 inch in the troff 
formatter). Setting tabs to other than the default values is the user’s responsibility. 

Default tab setting values are 9,17,25,._, 161 for a total of 20 tab stops. Values may be separated by commas, 
spaces, or any other non-numeric character. A user may set tab stops at any value desired. For example; 

.ta 9 17 25 33 41 49 57 „. 161 

A tab character is interpreted with respect to its position on the input line rather than its position on the 
output line. In general, tab characters should appear only on lines processed in no-fill (.nf) mode {3.1}. 
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The tbl(l) program {7.3} changes tab stops but does not restore default tab settings. 

3.6 BEL Character 

The nonprinting character BEL is used as a delimiter in many macros to compute the width of an argumen 
or to delimit arbitrary text, e.g., in page headers and footers {9}, headings |4}, and lists {5}. Users who indud. 
BEL characters in their input text file (especially in arguments to macros) will receive mangled output 

3.7 Bullets 

A bullet (•) is often obtained on a typewriter terminal by using an “o” overstruck by a For compatibil 
lty with the troff formatter, a bullet string is provided by MM with the following sequence: 

\*(BU 

The bullet list (.BL) macro {5.1.1.2} uses this string to generate automatically the bullets for bullet-listed items 

3.8 Dashes, Minus Signs, and Hyphens 

The troff formatter has distinct graphics for a dash, a minus sign, and a hyphen; the nroff formatter doei 


* U Th \ h ° intCDd t0USethe nroff formatt « r only may use the minus sign (-) for the minus, hyphen, 


e Users who plan to use the troff formatter primarily should follow troff escape conventions. 

e Users who plan to use both formatters must take care during input text file preparation. Unfortunately 
these graphic characters cannot be represented in a way that is both compatible and convenient for both 
formatters. 

The following approach is suggested: 

ACTION 

Type \*(EM for each text dash for both nroff and troff formatters. This string generates 

an em dash in the troff formatter and two dashes (-) in the nroff formatter. Dash list 

(.DL) macros {5.2.1.3} automatically generate the em dash for each list item. 

Type - and use as is for both formatters. The nroff formatter will print it as is and the 
troff formatter will print - (a true hyphen). 

Type \- for a true minus sign regardless of formatter. The nroff formatter will effectively 
ignore the the troff formatter will print a true minus sign. 

3.9 Trademark String 

strin * \*< Tm is available with MM. This places the letters **TM” one-half line above the text 
that it follows. For example: 

The 

J 

User’s Manual—UNIX 


SYMBOL 

Dash 

Hyphen 

Minus 
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\h*-lV(Tm 

.1 

Operating System 
.R 

is available from the library. 

yields; 

The User’s Manual— UNIX™ Operating System is available from the library. 

3.10 Uu of Formatter Request* 

Most formatter requests should not be used with MM because MM provides the corresponding formatting 
functions in a much more user-oriented and surprise-free fashion than do the basic formatter requests. Howev¬ 
er, some formatter requests are useful with MM, namely the following; 

.af Assign format 

.br Break 

.ce Center 

.de Define macro 

.ds Define string 

ii Fill output lines 

.hw Exception word 

is Line spacing 

.nf No filling of output lines 

.nr Define and set number register 

.nx Go to next file (does not return) 

jm Remove macro 

jt Remove register 

.rs Restore spacing 

.so Switch to source file and return 

.sp Space 

.ta Tab stop settings 

.ti Temporary indent 

.tl Title 

.tr Translate 

.! Escape 

The Jp, Jg, and .ss requests are also sometimes useful for the troff formatter. Use of other requests with¬ 
out fully understanding their implications very often leads to disaster. 

4. Paragraphs and Headings 

4.1 Paragraphs 

.P [type] 

one or more lines of text 

The J* macro is used to control paragraph style. 

4.1.1 Paragraph Indention 

An indented or a nonindented paragraph is defined with the type argument. 
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type Result 

0 left justified 

1 indent 

In a left-justified paragraph, the first line begins at the left margin. In an indented paragraph, the para¬ 
graph is indented the amount specified in the Pi register (default value is 5). For example, to indent paragraphs 
by ten spaces, the following is entered at the beginning of the document input file: 

.nr Pi 10 

A document input file possesses a default paragraph type obtained by specifying “.P” before each paragraph 
that does not follow a heading {4i}. Default paragraph type is controlled by the Pt number register. The ini ti al 
value of Pt is 0, which provides left-justified paragraphs. 

All paragraphs can be forced to be indented by inserting the following at the beginning of the document 
input file’ 

Jir Pt 1 

All paragraphs can be indented except after headings, lists, and displays by entering the following at the 
beginning of the document input file 

.nr Pt 2 

Both the Pi and Pt register values must be greater than zero for any paragraphs to be indented. 

Note: Values that specify indentation must be unsealed and are treated as character positions, i.e., as 
a number of ens. In the nroff formatter, an en is equal to the width of a character. In the troff formatter, 
an en is the number of points (1 point ■ 1/72 of an inch) equal to half the current point size. 

Regardless of the value of Pt; an individual paragraph can be forced to be left-justified or indented. The 
"• P 0” macro request forces left justification; “J> 1” causes indentation by the amount specified by the register 


If .P occurs inside a list, the indent (if any) of the paragraph is added to the current list indent {5}. 

4.1.2 Numbered Paragraphs 

Numbered paragraphs may be produced by setting the Np register to 1. This produces paragraphs numbered 
within first level headings, $.g., 1.01,1.02,1.03, 2.01, etc. 

A different style of numbered paragraphs is obtained by using the jaP macro rather than the JP macro for 
paragraphs. This produces paragraphs that are numbered within second level headings. 

M 1 - FIRST HEADING - 
.H 2 " Second Heading " 

.nP 

one or more lines of text 

The paragraphs contain a “double-line indent” in which the text of the second line is indented to be aligned with 
the text of the first line so that the number stands out 

4.1.3 Spacing Between Paragraphs 

The Ps number register controls the amount of spacing between paragraphs. By default Ps is set to 1, yield¬ 
ing one blank space (one-half a vertical space). 
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4.2 Numbered Headings 

Ji level (heading-text] [heading-suffix] 
zero or more lines of text 

The .H macro provides seven levels of numbered headings. Level 1 is the highest; level 7 the lowest 

The heading-suffix argument is appended to the beading-text argument and may be used for footnote marks 
which should not appear with heading text in the table of contents. 

Note: There is no need for a .P macro immediately after a .H or .HU (4.3} because the .H macro also 
performs the function of the .P macro. Any immediately following .P macro is ignored. It is, however, good 
practice to start every paragraph with a macro, thereby ensuring that all paragraphs uniformly begin 
with a .P throughout an entire document 

4.2.1 Normal Appoaranco 

The effect of the .H macro varies according to argument level. First-level headings are preceded by two 
blank lines (one vertical space); all others are preceded by one blank line (one-half a vertical space). The follow¬ 
ing table describes the default effect of the level argument 


.H 1 heading-text 


.H 2 heading-text 


.H n heading-text 


Produces a bold font heading followed by a single blank line (one- 
half a vertical space). The following text begins on a new line and is 
indented according to the current paragraph type. Full capital let¬ 
ters should normally be used to make the heading stand out 

Produces a bold font heading followed by a single blank line (one- 
half a vertical space). The following text begins on a new line and is 
indented according to the current paragraph type. Normally, initial 
capitals are used. 

Produces an underlined (italicized) heading followed by two spaces 
(3 < n < 7). The following text begins on the same line, i.e., these are 
run-in headings. 


Appropriate numbering and spacing (horizontal and vertical) occur even if the heading-text argument is 
omitted from a .H macro call. 

The following listing gives the first few .H calls used for this part. 

.H 1 " paragraphs and headings " 

J1 2 " Paragraphs " 

.H 3 • Paragraph Indention " 

.H 3 ’ Numbered Paragraphs " 

.H 3 " Spacing Between Paragraphs " 

.H 2 " Numbered Headings " 

.H 3 “ Normal Appearance " 

.H 3 " Altering Appearance " 

.H 4 ’ Prespacing and Page Ejection " 

,H4 * Spacing After Headings " 

.H 4 ’ Centered Headings " 
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4 " Bold, Italic, and Underlined Headings" 

.H 5 “Control by Level" 

Note: Users satisfied with the default appearance of headings may skip to the paragraph entitled “U; 
numbered Headings” {4.3}. 

4.2.2 Altering Appearance 

The user can modify the appearance of headings quite easily by setting certain registers and strings at tl 
beginning of the document input text file. This permits quick alteration of a document's style because this styl 
control information is concentrated in a few lines rather than being distributed throughout the document. 

4.2.2.1 Prtspaang and Pag* Ejection 

A first-level heading (.H1) normally has two blank lines (one vertical space) preceding it, and all other hea< 
ings are preceded by one blank line (one-half a vertical space). If a multiline heading were to be split aero: 
pages, it is automatically moved to the top of the next page. Every first-level heading may be forced to the to 
of a new page by inserting 

.nr Ej 1 

at the beginning of the document input text file. Long documents may be made more manageable if each sectio 
starts on a new page. Setting the Ej register to a higher value causes the same effect for headings up to th 
level, i.e., a page eject occurs if the heading level is less than or equal to the Ej value. 

4.2.2.2 Spodng After Headings 

Three registers control the appearance of text immediately following a .H call. The registers are Hb (heai 
ing break level), Hs (heading space level), and Hi (post-heading indent). 

If the heading level is less than or equal to Hb, a break {3.1} occurs after the heading. If the heading lev 
is less than or equal to Ha a blank line (one-half a vertical space) is inserted after the heading. The defat 
value for Hb and Hs is 2. If a heading level is greater than Hb and also greater than Hs, then the heading ( 
any) is run into the following text. These registers permit headings to be separated from the text in a consister 
way throughout a document while allowing easy alteration of white space and heading emphasis. 

For any stand-alone heading, i.e., a heading not run into the following text, alignment of the next line < 
output is controlled by the Hi register. 

• If Hi is 0, text is left-justified. 

• If Hi is 1 (the default value), text is indented according to the paragraph type as specified by the Pt rei 
ister {4.1}. 

• If Hi is 2, text is indented to line up with the first word of the heading itself so that the heading numb* 
stands out more clearly. 

To cause a blank line (one-half a vertical space) to appear after the first three heading levels, to have n 
run-in headings and to force the text following all headings to be left-justified (regardless of the value of Pt 
the following should appear at the beginning of the document input text file: 

.nr Hs 3 
.nr Hb 7 
.nr Hi 0 
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4.2.2.3 Ctnltrtd Headings 

The He register can be used to obtain centered headings. A heading is centered if its level argument is less 
than or equal to He and if it is also a stand-alone heading {4.2.2-2J. The He register is 0 initially (no centered 
headings). 


4.2.2.4 Bold, Italic, and Undorlinod Headings 

4.2.2.4.1 Control by Level Any heading that is underlined by the nroff formatter is italicized by the troff 
formatter. The string HF (heading font) contains seven codes that specify fonts for heading levels 1 through 
7. Legal codes, code interpretations, and defaults for HF codes are: 



MF CODE 






DEFAULT 

FORMATTER 

1 

2 

3 

HF CODE 

nroff 

no underline 

underline 

bold 

3322222 

troff 

Roman 

italic 

bold 

3 3 2 2 *2 2 2 


Thus, levels 1 and 2 are bold; levels 3 through 7 are underlined by the nroff formatter and italicized by the 
troff formatter. The user may reset HF as desired. Any value omitted from the right end of the list is assumed 
to be a 1. The following request would result in five bold levels and two Roman font levels: 

.ds HF 3 3 3 3 3 

4. 2 . 2 . 4. 2 NROFF Underlining Style: The nroff formatter underlines in either of two styles: 

• The normal style (.ul request) is to underline only letters and digits. 

• The continuous style (.cu request) underlines all characters including spaces. 

By default, MM attempts to use the continuous style on any heading that is to be underlined and is short enough 
to fit on a single line. If a heading is to be underlined but is longer than a single line, the heading is underlined 
in the normal style. 

All underlining of headings can be forced to the normal style by using the -rUl flag when invoking the 
nroff formatter {2.4}. 

4.2.2.4.3 Heading Point Sizes: The user may specify the desired point size for each heading level with the HP 
string (for use with the troff formatter only). 

.ds HP [psl] [ps2] [ps3] lps4] [ps5] [ps6] [ps7] 

By default, the text of headings (.H and .HU) is printed in the same point size as the body except that bold 
stand-alone headings are printed in a size one point smaller than the body. The string HP, similar to the string 
HF, can be specified to contain up to seven values, corresponding to the seven levels of headings. For example: 

•ds HP 12 12 10 10 10 10 10 

specifies that the first and second level headings are to be printed in 12-point type with the remainder printed 
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in 10-point. Specified values may also be relative point-size changes, for example: 
.ds HP +2 +2 -1 -1 


If absolute point sizes are specified, then absolute sizes will be used regardless of the point size of the body i 
the document. If relative point sizes are specified, then point sizes for headings will be relative to the poimsiz 
of the body even if the latter is changed. e 0 e 1)011,1 sa 


Null or aero values imply that default size will be used for the corresponding heading level. 


/Vote: Only the point size of the headings is affected. Specifying a large point size without providing 
creased vertical spacing (via .HX and/or .HZ) may cause overprinting. 


in 


4.2.2.S Marking Sly)**—Numeral* and Concatenation 


-HM {argl] ... [arg7] 


The registers named Hi through H7 are used as counters for the seven levels of headings. Register value 
are normaUy printed using Arabic numerals. The .HM macro (heading mark style) allows tliischoice to b< 
overridden thus providing outline and other document styles. This macro can have up to seven arguments 
each argument is a string indicating the type of marking to be used. Legal arguments and their meanings are 


A*GUM0<T 


MEANING 


1 

0001 

A 

a 

I 


Arabic (default for all levels) 

Arabic with enough leading zeroes to get the specified number of digits 
Uppercase alphabetic 
Lowercase alphabetic 
Uppercase Roman 


i Lowercase Roman 

Omitted arguments are interpreted as 1; illegal arguments have no effect. 


By default, the complete heading mark for a given level is built by concatenating the mark for that level 
o the right of all marks for all levels of higher value. To inhibit the concatenation of hea^ing levS mariS 
to obtain just the current level mark followed by a period, the heading mark type register {Ht) is set to 1. For 
example, a commonly used outline” style is obtained by: 


JiMI Alai 
-nr Ht 1 


4.3 Unnumbered Headings 
•HU heading-text 


The .HU macro is a special case of .H; it is handled in the same way as .H except that no heading marl 
L P h nn Hn h In H° rder t0 Pre ! er 3 the h . ierarchical structure of headings when .H and .HU calls are intermixed 

normal cas^the^ilfly'difference'betwoen* **'" by who!e is * * 


.HU heading-text 
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and 

.H 2 heading-text 

is the printing of the heading mark for the latter. Both macros have the effect of incrementing the numbering 
counter for level 2 and resetting to zero the counters for levels 3 through 7. Typically, the value of Hu should 
be set to make unnumbered headings (if any) be the lowest-level headings in a document 

The JiU macro can be especially helpful in setting up appendices and other sections that may not fit well 
into the numbering scheme of the main body of a document {14.2.1}. 

4.4 Heodingt and Table of Contents 

The text of headings and their corresponding page numbers can be automatically collected for a table of 
contents. This is accomplished by doing the following: 

e specifying in the contents level register, Cl, what level headings are to be saved 

# invoking the .TC macro {10.1} at the end of the document 

Any heading whose level is less than or equal to the value of the Cl register is saved and later displayed 
in the table of contents. The default value for the Cl register is 2, i.e., the first two levels of headings are saved. 

Due to the way headings are saved, it is possible to exceed the formatter’s storage capacity, particularly 
when saving many levels of many headings, while also processing displays {7} and footnotes {8}. If this happens, 
the “Out of temp file space” formatter error message (Table 4.D) will be issued; the only remedy is to save fewer 
levels and/or to have fewer words in the heading text 

4.5 Ftnt-L«v«l Hooding* and Pag* Numbering Style 

By default pages are numbered sequentially at the top of the page. For large documents, it may be desirable 
to use page numbering of the “section-page” form where “section” is the number of the current first-level head¬ 
ing. This page numbering style can be achieved by specifying the -rN3 or -rN5 flag on the command line {9.3}. 
As a side effect this also has the effect of setting Ej to 1, i.e., each first level section begins on a new page. In 
this style, the page number is printed at the bottom of the page so that the correct section number is printed. 

4.6 User Exit Macros 

Note: This paragraph is intended primarily for users who are accustomed to writing formatter macros. 

.HX dlevel rlevel heading-text 
.HY dlevel rlevel heading-text 
.HZ dlevel rlevel heading-text 

The .HX, .HY, and JLZ macros are the means by which the user obtains a final level of control over the 
previously described heading mechanism. These macros are not defined by MM. These macros are intended to 
be defined by the user. The .H macro invokes .HX shortly before the actual heading text is printed; it calls .HZ 
as its last action. After .HX is invoked, the size of the heading is calculated. This processing causes certain fea¬ 
tures that may have been included in .HX, such as .ti for temporary indent, to be lost. After the size calculation, 
.HY is invoked so that the user may respecify these features. All default actions occur if these macros are not 
defined. If .HX, .HY, or .HZ are defined by the user, user-supplied definition is interpreted at the appropriate 
point. These macros can therefore influence handling of all headings because the .HU macro is actually a special 
case of the .H macro. 

If the user originally invoked the .H macro, then the derived level (dlevel) and the real level ( rlevel) are both 
equal to the level given in the .H invocation. If the user originally invoked the .HU macro {4.3}, dlevel is equal 
to the contents of register Hu, and rlevel is 0. In both cases, heading-text is the text of the original invocation. 
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By the time .H calls .HX. it has already incremented the heading counter of the specified level {4.2JL5}, prc 
duced blank lines (vertical spaces) to precede the heading {4.2.2.1}, and accumulated the “heading marie”. L< 
the string of digits, letters, and periods needed for a numbered heading. When .HX is called, all user-accessibl 
registers and strings can be referenced, as well as the following; 

string }0 If rlevel is nonzero, this string contains the “heading mark”. Two unpaddable spaces (t 

separate the mark from the heading) have been appended to this string. If rlevel is 0, th 
string is null. 

register ;0 This register indicates the type of spacing that is to follow the heading {4.2.2.21. A valu 

of 0 means that the heading is run-in. A value of 1 means a break (but no blank line) i 
to follow the heading. A value of 2 means that a blank line (one-half a vertical space) i 
to follow the heading. 

If “register ;0” is 0, this string contains two unpaddable spaces that will be used to separat 
the (run-in) heading from the following text. If “register ;0” is nonzero, this string is nal 

This register contains an adjustment factor for a me request issued before the headin 
is actually printed. On entry to .HX, it has the value 3 if dlevel equals 1, and 1 otherwise 
The me request is for the following number of lines: the contents of the “register X take 
as blank lines (halves of vertical space) plus the contents of “register X as blank line 
(halves of vertical space) plus the number of lines of the heading. 

The user may alter the values of {0, }2, and ;3 within .HX. The following are examples of actions that migl 
be performed by defining .HX to include the lines shown: 


string }2 
register ;3 


• Change first-level heading mark from format u. to n.0: 

.if\\$l=l.ds }0\\n(HI.0\<sp>\<sp> 

(where <sp> stands for a space) 

• Separate run-in heading from the text with a period and two unpaddable spaces: 

.if \\n(;0=0 .ds} 2 A<sp>\<sp> 

• Assure that at least 15 lines are left on the page before printing a first-level heading: 
.if W $1=1 .nr ;3 15-\\n(;0 

• Add three additional blank lines before each first-level heading: 

.if \\ $1=1 .sp 3 

• Indent level 3 run-in headings by five spaces: 

.if \\ $1=3 .ti 5n 


If temporary strings or macros are used within .HX, their names should be chosen with care {14.1}. 

When the JIY macro is called after the .ne is issued, certain features requested in .HX must be repeated 
For example: 

.de HY 

-if \\$1=3 .ti 5n 
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The .HZ macro is called at the end of .H to permit user-controlled actions after the heading is produced. 
In a large document, sections may correspond to chapters of a book; and the user may want to change a page 
header or footer, e.g.: 

.de HZ 

.if \\$1«1 .PF" Section \\$3" 


4.7 Hints for Largo Documents 

A large document is often organized for convenience into one input text file per section. If the files are num¬ 
bered, it is wise to use enough digits in the names of these files for the maximum number of sections, i.e., use 
suffix numbers 01 through 20 rather than 1 through 9 and 10 through 20. 

Users often want to format individual sections of long documents. To do this with the correct section num¬ 
bers, it is necessary to set register HI to one less than the number of the section just before the corresponding 
.H\ 1 call. For example, at the beginning of Part 5, insert 

jir Hi 4 

Note: This is not good practice. It defeats the automatic (re)numbering of sections when sections 
are added or deleted. Such lines should be removed as soon as possible. 

5. list* 

This part describes different styles of lists; automatically numbered and alphabetized lists, bullet lists, dash 
lists, lists with arbitrary marks, and lists starting with arbitrary strings, i.e., with terms or phrases to be de¬ 
fined. 

5.1 List Macros 

In order to avoid repetitive typing of arguments to describe the style or appearance of items in a list, MM 
provides a convenient way to specify lists. All lists share the same overall structure and are composed of the 
following basic parts; 

• A list-initialization macro (.AL .BL, .DL, .ML, .RL, or .VL) determines the style of list line spacing, in¬ 
dentation, marking with special symbols, and numbering or alphabetizing of list items. 

• One or more list-item macros (XI) identifies each unique item to the system. It is followed by the actual 
text of the corresponding list item. 

• The list-end macro (XE) identifies the end of the list. It terminates the list and restores the previous 
indentation. 

Lists may be nested up to six levels. The list-initialization macro saves the previous list status (indentation 
marking style, etc.); the XE macro restores it 

With this approach, the format of a list is specified only once at the beginning of the list. In addition by 
building onto the existing structure, users may create their own customized sets of list macros with relatively 
little effort ({5.3} and {5.4}). 

5.1.1 UsMnitializoKon Macros 

List-initialization macros are implemented as calls to the more basic .LB macro {5.2}. 
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They are: 

.AL 

Automatically Numbered or Alphabetized List 


.BL 

Bullet List 


.DL 

Dash List 


.ML 

Marked List 


,RL 

Reference List 


-VL 

Variable-Item List 

5.1.1.1 Automatically Numborod or Alphabotizod List 


.AL [type] [text-indent] [1] 

The AL macro is used to begin sequentially numbered or alphabetized lists. If there are no arguments, th 
list is numbered; and text is indented by Li (initially six) spaces from the indent in force when the .AL is called 
This leaves room for a space, two digits, a period, and two spaces before the text Values that specify indentation 
must be unsealed and are treated as “character positions", i.e., number of ens. 

Spacing at the beginning of the list and between items can be suppressed by setting the list space register 
(Ls). The Ls register is set to the innermost list level for which spacing is done. For example: 

.nr Ls 0 

specifies that no spacing will occur around any list items. The default value for Ls is six (which is the maxim on 
list nesting level). 

• The type argument may be given to obtain a different type of sequencing. Its value indicates the first 
element in the sequence desired- If type argument is omitted or null, the value 1 is assumed. 

ARGUMENT INTERPRETATION 

1 Arabic (default for all levels) 

A Uppercase alphabetic 

a Lowercase alphabetic 

I Uppercase Roman 

i Lowercase Roman 

• If text-indent argument is non-null, it is used as the number of spaces from the current indent to thi 
text, i.e., it is used instead of Li for this list only. If text-indent argument is null, the value of Li wil] 
be used. 

• If the third argument is given, a blank line (one-half a vertical space) will not separate items in the list. 
A blank line will occur before the first item however. 

5.1.1.2 Bullet list 

.BL [text-indent] [1] 

The .BL macro begins a bullet list. Each list item is marked by a bullet (•) followed by one space. 

• If the text-indent argument is non-null, it overrides the default indentation (the amount of paragraph 
indentation as given in the Pi register [4.1}). In the default case, the text of bullet and dash lists lines 
up with the first line of indented paragraphs. 
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• If the second argument is specified, no blank lines will separate items in the list. 

S.l.1.3 Dash list 


6/12 


J)L [text-indent] [1] 

The J>L macro is identical to .BL except that a dash is used as the list item mark instead of a ballet 

5.1.1.4 Marirad list 


-ML mark [text-indent] [1] 


The ML macro is much like .BL and .DL macros but expects the user to specify an arbitrary mark which 
may consist of more than a single character. 

• Text is indented text-indent spaces if the second argument is not null; otherwise, the text is indented 
one more space than the width of mark 

• If the third argument is specified, no blank lines will separate items in the list 

Note: The mar* must not contain ordinary (paddable) spaces because alignment of items will be lost 
if the right margin is justified [3.3). 

S.1.1.5 Re f eren c e list 


JRL [text-indent] [1] 

A JtL macro call begins an automatically numbered list in which the numbers are enclosed by square brack¬ 
ets ([ ]). 

e If the text-indent argument is non-null, it is used as the number of spaces from the current indent to 
the text, i.e^ it is used instead of Li for this list only. If the text-indent argument is omitted or null, 
the value of Li is used. 

• If the second argument is specified, no blank lines will separate the items in the list 
5.1.1.6 Variable-Item list 


•VL text-indent [mark-indent] [1] 

When a list begins with a .VL macro, there is effectively no current mark ; it is expected that each LI will 
provide its own mark. This form is typically used to display definitions of terms or phrases. 

• Text-indent provides the distance from current indent to beginning of the text 

• Mark indent produces the number of spaces from current indent to beginning of the mark and it de¬ 
faults to 0 if omitted or null. 

• If the third argument is specified, no blank lines will separate items in the list 

An example of .VL macro usage is shown below: 

.tr % 

.VL 20 2 
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XI mark\l 

Here it a description of mark I; 

“mark 1" of th* XI lino contains a tilde 
translated to an unpaddable tpace in order 
to avoid extra tpaeea between 
“mark” and T {3.3}. 

XI eecondsmark. 

Thit it the tecond mark alto using a tilde translated to an unpaddable tD&ee 
XI thirdsmarkslongervthan^indent: F P 

Thit item ahowi the effect of a long mark; one tpace teparatea the mark from the text. 

.LI * 

This item effectively has no mark because the tilde following the XI is translated into a space 


when formatted yields; 

mark 1 Here it a description of mark 1; “mark 1" of the XI line contains a tilde translated to 

*n unpaddable ipaca in ordtr to avoid extra ipa ct% between *mark~ and “V {22 ,. 

second mark Thit it the tecond mark alto using a tilde translated to an unpaddable apace. 

third mark longer than indent: Thit item thowt the effect of a long mark; one apace separates the mark 
from the text 

This item effectively has no mark because the tilde following the XI is translated into 

a tpace. 


. ***•. ^roent on the last XI above ie required; otherwise, e “hanging indent" would have been pro¬ 

duced. A hanging indent ie produced by using .VL and calling XI with no arguments or with a null Cm 4- 
ment For example: 6 


.VL 10 
XI 

Here is some text to show a hanging indent 
The first line of text it at the left margin. 
The second is indented 10 spaces. 

XE 


when formatted yields: 

Here is some text to show a hanging indent The first line of text is at the left margin. The second is 
indented 10 spaces. “ 


Note: The mark must not contain ordinary (paddable) spaces because alignment of items will be lost 
if the right margin is justified {3.3}. 

5.1.2 List-Item Macro 


XI [mark] [1] 

one or more lines of text that make up the list item. 


t ' I ? e ,r LI m ^ ro 13 used ^ Us ts “ d for each list item. It normally causes output of a single biank 
(one-half a vertical space) before its list item although this may be suppressed. 




If no arguments are given, XI labels the item with the 
cent list-initialization macro. 


current mark which is specified by the most re- 
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• If a single argument is given, that argument is output instead of the current mark. 

• If two arguments are given, the first argument becomes a prefix to the current mark thus allowing the 
user to emphasize one or more items in a list. One unpaddable space is inserted between the prefix and 
the mark. 

For example: 

.BL6 

XI 

This is a simple bullet item. 

XI + 

This replaces the bullet with a “plus”. 

XI + 1 

This uses a “plus" as prefix to the bullet 
XE 

when formatted yields: 

• This is a simple bullet item. 

+ This replaces the bullet with a "plus". 

+ • This uses "plus” as prefix to the bullet 

Note: The mark must not contain ordinary (paddable) spaces because alignment of items will be lost 
if the right margin is justified (3.3). 

If the current mark (in the current list) is a null string and the first argument of XI is omitted or null, the 
resulting effect is that of a "hanging indent”, i.e., the first line of the following text is moved to the left starting 
at the same place where mark would have started {5.1.1.6}. 

5.1.3 List-End Mocr® 

XE [1] 

The XE macro restores the state of the list to that existing just before the most recent list-initialization 
macro call. If the optional argument is given, the XE outputs a blank line (one-half a vertical space). This option 
should generally be used only when the XE is followed by running text but not when followed by a macro that 
produces blank lines, of its own such as the .P, Ji, or XI macro. 

The .H and -HU macros automatically clear all list information. The user may omit the XE macros that 
would normally occur just before either of these macros and not receive the "LEmismatched” error message. 
Such a practice is not recommended because errors will occur if the list text is separated from the heading at 
some later time (e.g., by insertion of text). 

5.1.4 Example of Nested lists 

An example of input for the several lists and the corresponding output is shown below. The .AL and .DL 
macro calls {5.1.1] contained therein are examples of list-initialization macros. Input text is: 

ALA 

XI 

This is alphabetized list item A. 
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This text shows the alignment of the second line 
of the item. 

Notice the text indentations and alignment of left 
and right margins. 

.AL 

U 

This is numbered item 1. 

This text shows the alignment of the second line 
of the item. 

The quick brown fox jumped over the lazy dog’s back. 

XL 

XI 

This is a dash item. 

This text shows the alignment of the second line 
of the item. 

The quick brown fox jumped over the lazy dog's back. 
XI + 1 


This is a dash item with a “plus” as prefix. 

This text shows the alignment of the second line of the item. 
The quick brown fox jumped over the lazy dog’s back. 


XE 

XI 

This is numbered item 2. 

XE 

XI 


This is another alphabetized list item B. 

This text shows the alignment of the second line 
of the item. 

The quick brown fox jumped over the lazy dog’s back. 
XE 


This paragraph follows a list item and is aligned 
the left margin. 

A paragraph following a list resumes the normal 
length and margins. 


with 

line 
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The output is: 


A. This is alphabetised list item A. This text shows the alignment of the second line of the 
item. Notice the text indentions and alignment of left and right margins. 

1. This is numbered item 1. This text shows the alignment of the second line of the 
item. The quick brown fox jumped over the lazy dog’s back 

• This is a dash item. This text shows the alignment of the second line of the 
item. The quick brown fox jumped over the lazy dog’s back. 

+ - This is a dash item with a “plus” as prefix. This text shows the alignment 
of the second line of the item. The quick brown fox jumped over the lazy 
dog’s back. 


2. This is numbered item 2. 


B. This is another alphabetized list item B. This text shows the alignment of the second line 
of the item. The quick brown fox jumped over the lazy dog’s back. 


This paragraph follows a list item and is aligned with the left margin. A paragraph following a list resumes 
the normal line length and margins. 


5.2 list-Bogin Macro and Customized lists 

LB text-indent mark-indent pad type [mark] [LI-space]\[LB-space] 

List-initialization macros described above suffice for almost all cases. However, if necessary, the user may 
obtain more control over the layout of lists by using the basic list-begin macro (.LB). The 1<B macro is used 
by the other list-initialization macros. Its arguments are as follows: 


• The text-indent argument provides the number of spaces that text is to be indented from the current 
indent. Normally, this value is taken from the Li register (for automatic lists) or from the Pi register 
(for bullet and dash lists). 


• The combination of mark-indent and pad arguments determines the placement of the mark. The mark 
is placed within an area (called mark area) that starts mark-indent spaces to the right of the current 
indent and ends where the text begins (i.e n ends text-indent spaces to the right of the current indent). 
The mark-indent argument is typically 0. 


• Within the mark area, the mark is left justified if the pad argument is 0. If pad is a number n (greater 
than 0) then n blanks are appended to the mark; the mark-indent value is ignored. The resulting string 
immediately precedes the text. The mark is effectively right justified pad spaces immediately to the left 
of text 


• Arguments type and mark interact to control the type of marking used. If type is 0, simple marking is 
performed using the mark characters) found in the mark argument If type is greater than 0, automatic 
numbering or alphabetizing is done; and mark is then interpreted as the first item in the sequence to 
be used for numbering or alphabetizing, i.e., it is chosen from the set (1, A, a, I, i) as in {5.1.1.1}. This 
is summarized in the following table . 
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type 

mark 

result 

0 

omitted 

hanging indent 

0 

string 

string is the mark 

>0 

omitted 

Arabic numbering 

>0 

one of: 

1. A, a, I, i 

automatic numbering or 
alphabetic sequencing 


Each nonzero value of type from one to six selects a different way of displaying the marks. The following 
table shows the output appearance for each value of type: 




VALUC APFEARANd 


1 X. 

2 x) 

3 (x) 

4 lx] 

5 <x> 

6 lx] 


where x is the generated number or letter. 

Note: The mark must not contain ordinary (paddable) spaces because alignment of items will be lost 

if the right margin is justified {3.3}. 

• The U-space argument gives the number of blank lines (halves of a vertical space) that should be output 
by each XI macro in the list If omitted, U-space defaults to 1; the value 0 can be used to obtain compact 
lists. If U-space is greater than 0, the XI macro issues a j»e request for two lines just before printing 
the mark. 

• The LB-space argument is the number of blank lines (one-half a vertical space) to be output by XB itself 
If omitted LB-space defaults to 0. 

There are three combinations of U-space and LB-space : 

• The normal case is to set U-space to 1 and LB-space to 0 yielding one blank line before each item in 
the list; such a list is usually terminated with a XE 1 macro to end the list with a blank line. 

• For a more compact list, U-space is set to 0, LB-space is set to 1, and the XE 1 macro is used at the 
end of the list The result is a list with one blank line before and after it 

• If both U-space and LB-space are set to 0 and the .LE macro is used to end the list a list without anv 
blank lines will result. 

Paragraph {5.3} shows how to build upon the supplied list of macros to obtain other kinds of lists. 

5.3 User-Defined List Structures 

Note: This part is intended only for users accustomed to writing formatter macros. 

If a large document requires complex list structures, it is useful to define the appearance for each list level 
only once instead of having to define the appearance at the beginning of each list. This permits consistency of 


Pag* 183 



DOCUMENT PROCESSING GUIDE 


ISSUE 1 


6/82 


style in a large document. A generalized list-initialization macro might be defined in such a way that what the 
macro does depends on the list-nesting level in effect at the time the macro is called. Levels 1 through 5 of the 
lists to be formatted may have the following appearance: 

A. 

( 1 ) 


a) 

+ 


The following code defines a macro (.aL) that always begins a new list and determines the type of list accord¬ 
ing to the current list level. To understand it, the user should know that the number register :g is used by the 
MM list macros to determine the current list level; it is 0 if there is no currently active list Each call to a list- 
initialization macro increments :g, and each XE call decrements it 



\" register g is used as a local temporary to save 

\" :g before it is changed below 

.de aL 

.nr g \\n(:g 

if \\ng=0 .AL A \" produces an A. 

•if \\ng-l .LB \\n(Li 014 \" produces a {1] 

if \\ng-2 .BL \" produces a bullet 


.if \\ng=3 XB \\n(Li 0 2 2a 
if \\ng=4 .ML + 


\" produces an a) 
\" produces a + 


This macro can be used (in conjunction with XI and XE) instead of AX -EX XX -LB, and .MX For example, 
the following input 



First line. 

.aL 

XI 

Second line. 

XE 

XI 

Third line. 
XE 


when formatted yields 

A. First line. 


[1] Second line. 
B. Third line. 
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There is another approach to list* that ia similar to the .H mechanism. List-initialization, as well as the 
XI and the XE macros, are all included in a single macro. That macro (defined as .bL below) requires an argu¬ 
ment to tell it what level of item is required; it adjusts the list level by either beginning a new list or setting 
the list level back to a previous value, and then issues a XI macro call to produce the item. 

.de bL 

.ie \\n(.$ .nr g \\$1 \" if there is an argument, 

\" that is the level 

.el .nr g \\n(:g \" if no argument, use current level 

•if \\ng—\\n(:g> 1 .)D \" ••ILLEGAL SKIPPING OF LEVEL 

V increasing level by more than 1 
•if \\ng>\\n(:g \{.aL \\ng-l \" if g > :g, begin new list 

•nr \" and reset g to current level 

V (.aL changes g) 

•if \\n(:g>\\ng XC \\ng \" if :g > g, prune back to 

\" correct level 

V if :g - g, stay within 

V current list 

XI \" in all cases, get out an item 


For .bL to work, the previous definition of the .aL macro must be changed to obtain the value of gfrom its 
argument rather than from :g Invoking .bL without arguments causes it to stay at the current list level. The 
.LC (List Clear) macro removes list descriptions until the level is less than or equal to that of its argument For 
example, the Ji macro includes the call “.LC 0”. If text is to be resumed at the end of a list insert the call “XC 
0” to clear out the lists completely. The example below illustrates the relatively small amount of input needed 
by this approach. The input text 

The quick brown fox jumped over the lazy dog’s back. 

.bL 1 

First line. 

.bL 2 

Second line. 

.bL 1 

Third line. 

.bL 

Fourth line. 

XCO 
Fifth line. 

when formatted yields 

The quick brown fox jumped over the lazy dog’s back. 

A. First line. 

[1] Second line. 

B. Third line. 

C. Fourth line. 

Fifth line. 
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6. Memorandum and Relaated-Popar Stylo Document* 

One use of MM is for the preparation of memoranda and released-paper documents (a documentation style 
used by Bell Laboratories, Inc.) which have special requirements for the first page and for the cover sheet Data 
needed (title, author, date, case numbers, etc.) is entered the same for both styles; an argument to the JKT 
macro indicates which style is being used. 

6.1 Sequence of Beginning Macro* 

Macros, if present must be given in the following order: 


JTD new-date 

,TL [charging-case] [filing-case] 
one or more lines of text 
AF [company-name] 

AU name [initials] [loc] [dept] [ext] [room] [arg] [arg] 

AT [title] - 
,TM [number] — 

AS [arg] [indent] 

one or more lines of text 

AE 

•NS [arg] 

one or more lines of text 

m 

.OK [keyword] ~ 

-MT [type] [addressee] 

The only required macros for a memorandum for file or a released-paper document are .TL, AU, and JIT; 
all other macros (and their associated input lines) may be omitted if the features are not needed. Once .MT has 
been invoked, none of the above macros (except .NS and .NE) can be reinvoked because they are removed from 
the table of defined macros to save memory space. 

If neither the memorandum nor released-paper document style is desired, the TL, AU, TM, AE, OK, MT, 
ND, and AF macros should be omitted from the input text If these macros are omitted, the first page will have 
only the page header followed by the body of the document. 


6.2 Title 


.TL [charging-case] [filing-case] 
one or more lines of title text 


Arguments to the .TL macro are the charging-case number(s) and filing-case number(s). 

e The charging-c&se argument is the case number to which time was charged for the development of the 
project described in the memorandum. Multiple charging - case numbers are entered as “subarguments” 
by separating each from the previous with a comma and a space and enclosing the entire argument 
within double quotes. 

• The filing-c&se argument is a number under which the memorandum is to be filed. Multiple filing case 
members are entered similarly. For example: 

.TL “1 234 5, 6789 0" 987654321 
Construction of a Table of all Even Prime numbers 

The title of the memorandum or released-paper document follows the .TL macro and is processed in fill mode. 
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The .br request may be used to break the title into several lines as follows; 


.TL 12345 
First Title Line 
•br 
\!.br 

Second Title Line 


On output, the title appears after the word “subject’ 
in the released-paper document style. 


in the memorandum style and is centered and bolt 


If only a charging case number or only a filing case number is given, it will be separated from the title L 
the memorandum style by a dash and will appear on the same line as the title. If both case numbers are rivei 
“f same ’ then “C har * in 8 *nd Filing Case” followed by the number will appear on a line following th< 

thetiUe the tW ° C * S * DUmberS are dlffercnt ’ “Pa™* lines for “Charging Case” and “File Case” will appearaftei 


6.3 Authors 


.AU name (initials) [loc] (dept) (ext) [room] (arg] [arg] 
•AT [title] 


'P* macro receives as arguments information that describes an author. If any argument contains 
b anks, that argument must be enclosed within double quotes. The first six arguments must appear in the order 
given. A separate .AU macro is required for each author. 


The .AT macro is used to specify the author's title. Up to nine arguments may be given. Each will apoea 
in the signature block for memorandum style (6.11) on a separate line following the signer's name. The AT mui 
immediately follow the AU for the given author. For example: 


AU " J. J. Jones " JJJ PY 9876 5432 1Z-234 
AT Director " Materials Research Laboratory " 


In the “from portion in the memorandum style, the author's name is followed by location and department 
number on one line and by room number and extension number on the next. The “x” for the extension is added 
automatically. Printing of the location, department number, extension number, and room number may be sup- 
pressed on the firstpage of a memorandum by setting the register Au to 0; the default value for Aa bL Arcu- 
through 9 of .. the ^ “aero, if present, will follow this normal author information in the “from" portion, 
each on a separate line. These last three arguments may be used for organizational numbering schemes, etc. 


AU " S. P. Lename " SPL IH 9988 7766 5H-444 9876-543210.01MF 


the ltx ? tion ' *** department are also used in the signature block Author information ii 

the from portion, as well as names and initials m the signature block will appear in the same order as th« 
.a u macros. 


t i* r *J* ase J 1 ‘P a P er centered below the title. Following the name of the last 

'll'™ Uboratones and the location are centered. The paragraph on memorandum types {6.7} contaSs 
information regarding authors from different locations. 1 ’ 


6.4 TM Number* 


.TM [number] ... 

If the memorandum is a technical memorandum, the TM numbers are supplied via the .TM macro. Up to 
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AS [arg] [indent] 
text of abstract 
AE 


If a memorandum has an abstract, the input is identified with the AS (abstract start) and AE (abstract 
end) delimiters. Abstracts are printed on page 1 of a document and/or on its cover sheet There are three styles 
of cover sheet 


• released paper 


technical memorandum 


• memorandum for file {10.2} (also used for engineer’s notes, memoranda for record, etc.). 

Cover sheets for released papers and technical memoranda are obtained by invoking the .CS macro {10.2}. 

In released-paper style (first argument of the .MT macro {6.7} is 4) and in technical memorandum style if 
the first argument of AS is: 

0 Abstract will be printed on page> 1- and on the cover sheet (if any). 

1 Abstract will appear only on the cover sheet (if any). 


In memoranda for file style and in all other documents (other than external letters) if the first argument of 

.AS is: 


0 Abstract will appear on page 1 and there will be no cover sheet printed. 


2 Abstract will appear only on the cover sheet which will be 
voking the .CS macro). 


produced automatically (Le^ without in' 



It is not possible to get either an abstract or a cover sheet with an external letter (first argument of the JIT 
macro is 5). 


Notations such as a “copy to" list {6.11} are allowed on memorandum for file cover sheets; the JJS and .NE 
macros must appear after the .AS 2 and .AE macros. Headings {4.2,4.3} and displays {7} are not permitted within 
an abstract 


The abstract is printed with ordinary text margins; an indentation to be used for both margins can be speci¬ 
fied as the second argument of AS. Values that specify indentation must be unsealed and are treated as “charac¬ 
ter positions”, i.e., as the number of ens. 

6.6 Other Keywords 

.OK [keyword] ... 

Topical keywords should be specified on a technical memorandum cover sheet Up to nine such keywords 
or keyword phrases may be specified as arguments to the .OK macro; if any keyword contains spaces, it must 
be enclosed within double quotes. 
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6.7 Memorandum Typos 

.MT [type] [addressee] 

The .MT macro controls the format of the top part of the first page of a memorandum or of a released-pap< 
document and the format of the cover sheets. The type arguments and corresponding values are: 

Value 

no memorandum type printed 

no memorandum type printed 

MEMORANDUM FOR FILE 

MEMORANDUM FOR FILE 

PROGRAMMER’S NOTES 

ENGINEER'S NOTES 

released-paper style 

external-letter style 

string (enclosed in quotes) 

If the type argument indicates a memorandum style document, the corresponding statement indicatec 
under "Value” will be printed after the last line of author information. If type is longer than one character, thei 
the string itself will be printed. For example: 

.MT " Technical Note #5" 

A simple letter is produced by calling MT with a null (but not omitted) or 0 argument 

The second argument to MT is the name of the addressee of a letter. If present that name and the page 
number replace the normal page header on the second and following pages of a letter. For example: 

MT 1" John Jones” 

produces 

John Jones — 2 

The addressee argument may not be used if the first argument is 4 (released-paper style document). 

The released-paper style is obtained by specifying 
•MT 4 [1] 

This results in a centered, bold title followed by centered names of authors. The location of the last author is 
used as the location following “Bell Laboratories” (unless the .AF macro specifies a different company) If the 
optional second argument to MT 4 is given, then the name of each author is followed by the respective company 


type 


0 

none 

1 

2 

3 

4 

5 

" string 
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name and location. Information necessary for the memorandum style document but not for the released-oaoer 
style document is ignored. ^ 

If the released-paper style document is utilized, most BTL location codes are defined as strings that are the 
addresses of the corresponding BTL locations. These codes are needed only until the .MT macro is invoked. Thus, 
following the MT macro, the user may reuse these string names. In addition, the macros for the end of a memo¬ 
randum f6.ll} and their associated lines of input are ignored when the released-paper style is specified. 

Authors from non-BTL locations may include their affiliations in the released-paper style by specifying the 

appropriate AF macro {6.9} and defining a string (with a 2-character name such as ZZ) for the address before 
each AU. For example: 


.TL 

A Learned Treatise 
AF " Getem Inc." 


.ds ZZ " 22 Maple Avenue, Sometown 09999" 


AU "F. Swatter" "" ZZ 
AF " Bell Laboratories" 
AU " Sam P. Lename" * " 
.MT 4 1 


CB 



In the external-letter style document (.MT 5), only the title (without the word “subject”) and the date are 
printed m the upper left and nght corners, respectively, on the first page. It is expected that preprinted statio- 
nery wili be used with the company logo and address of the author. 

6.8 Dote Changes 

-ND new-date 


The .ND macro alters the value of the string £>T, which is initially set to produce the current date. If the 
argument contains spaces, it must be enclosed within double quotes. 

6.9 Alternate Rrsf-Poge Fermat 

AF (company-name) 

u t ^ ^ te ™ ate first-page format can be specified with the AF macro.. The words “subject”, “date”, and 
from (m the memorandum style) are omitted and an alternate company name is used. 

If an argument is given, it replaces “Bell Laboratories” without affecting other headings. If the argument 
is null, “Bell Laboratories is suppressed; and extra blank lines are inserted to allow room for stamping the doc- 
ument with a Bell System logo or a Bell Laboratories stamp. 


The AF with no argument suppresses “Bell Laboratories” and the “Subject/Date/From” headings, thus 
allowing output on preprinted stationery. The use of AF with no arguments is equivalent to the use of -rAl 
{2.4}, except that the latter must be used if it is necessary to change the line length and/or page offset (which 
default to 5.8i and li, respectively, for preprinted forms). The command line options — , rOk and —rWk {2.41 are 

not effective with -AF. The only AF use appropriate for the troff formatter is to specify a replacement for “Bell 
Laboratories”. 

The command line option -rEn {2.4} controls the font of the "Subject/Date/From” block. 

6.10 Example 

Input text for a document may begin as follows: 

.TL 
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MM\*(EMMemorandum Macros 

.AU" D. W. Smith" DWS PY 

.AU"J. Ft Mashey" JRM PY 

.AU " E. C. Pariser (January 1980 Revisionr ECP PY 

•AU " N. W. Smith (June 1980 Revisionr NWS PY 

.MT4 

Figure 4.1 shows the input text file and both the nroff and troff formatter outputs for a simple letter. 
6.11 End of Memorandum Macros 

At the end of a memorandum document (but not of a released-paper document), signatures of authors and 
a list of notations can be requested. The following macros and their input are ignored if the released-paper style 
document is selected. 

6.11.1 Signature Block 

SC (dosing] 

•SG (arg) [1] 

The SC macro prints “Yours very truly,” as a formal closing, if no argument is used. It must be given before 
the .SG macro. A different dosing may be specified as an argument to .FC. 

The .SG macro prints the author’s name(s) after the formal closing, if any. Each name begins at the center 
of the page. Three blank lines are left above each name for the actual signature. 

o If no arguments are given, the line of reference data (location code, department number, author’s ini¬ 
tials, and typist’s initials, all separated by hyphens) will not appear. 

o A non-null first argument is treated as the typist’s initials and is appended to the reference data 

• A null first argument prints reference data without the typist’s initials or the preceding hyphen. 

• If there are several authors and if the second argument is given, reference data is pla ce d on* the line 
of the first author. 

Reference data contains only the location and department number of the first author. Thus, if there are au¬ 
thors from different departments and/or from different locations, the reference data should be supplied manu¬ 
ally after the invocation (without arguments) of the .SG macro. For example: 

.SG 

.rs 

.sp -lv 

PY/MH-9876/5432-JJJ/SPL-cen 

6.11.2 "Copy to" and Other Notation* 

.NS [arg] 

zero or more lines of the notation 
NTE 

Many types of notations (such as a list of attachments or “Copy to’’ lists) may follow signature and reference 
data. Various notations are obtained through the .NS macro, which provides for proper spacing and for break¬ 
ing notations across pages, if necessary. 
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Codes for arg and the corresponding notations are: 


Notations 


0 

1 

2 

3 

4 

5 

6 

7 

8 
9 


none 


Copy to 
Copy to 
Copy to 

Copy (with att) to 
Copy (without att) to 
Att 
Atts. 

Enc. 

Encs. 

Under Separate Cover 
Letter to 
Memorandum to 


string Copy (string) to 



If arg consists of more than one character, it is placed within parentheses between the words “Copy” and 
“to”. For example: 


.NS * with att 1 only * 

will generate 

Copy (with att 1 only) to 

m 

as the notation. More than one notation may be specified before the .NE macro because a .NS macro terminates 
the preceding notation, if any. For example: 


.NS 4 

Attachment l*List of register names 
Attachment 2-List of string and macro names 
.NS1 
J. J. Jones 
.NS 2 

S. P. Lename 
G. H. Hurtz 

m 



would be formatted as 
Atts. 

Attachment 1—List of register names 
Attachment 2—List of string and macro names 

Copy (with att.) to 
J. J. Jones 

Copy (without att) to 
S. P. Lename 
G. H. Hurtz 

The .NS and .NE macros may also be used at the beginning following .AS 2 and .AE to place the notation 
list on the memorandum for Hie cover sheet {6.5}. If notations are given at the beginning without AS 2, they 
will be saved and output at the end of the document 
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6.11.3 Approval Signature Uno 

.AV approver’s-name 

The .AV macro may be used after the last notation block to automatically generate a line with spaces for 
the approval signature and date. For example: 

.AV" Jane Doe " 

produces 

APPROVED: 


Jane Doe Date 

6.12 One-Pago Lott or 

At times, the user may like more space on the page forcing the signature or items within notations to the 
bottom of the page so that the letter or memo is only one page in length. This can be accomplished by increasing 
the page length with the ~rLn option, e.g., — rL90. This has the effect of making the formatter believe that the 
page is 90 lines long and therefore providing more space than usual to place the signature or the notations. 

Note: This will work only for a single-page letter or memo. 

7. Displays 

Displays are blocks of text that are to be kept together on a page and not split across pages. They are pro¬ 
cessed in an environment that is different from the body of the text (see the .ev request). The MM package pro¬ 
vides two styles of displays—a static (.DS) style and a floating (.DF) style. 

• In the static style, the display appears in the same relative position in the output text as it does in the 
input text This may result in extra white space at the bottom of the page if the display is too long to 
fit in the remaining page space. 

• In the floating style, the display “floats” through the input text to the top of the next page if there is 
not enough space on the current page. Thus input text that follows a floating display may precede it 
in the output text A queue of floating displays is maintained so that their relative order of appearance 
in the text is not disturbed. 

By default, a display is processed in no-fill mode with single spacing and is not indented from the existing 
margins. The user can specify indentation or centering as well as fill-mode processing. 

Note: Displays and footnotes {8} may never be nested in any combination. Although lists {5} and para¬ 
graphs {4.1} are permitted, no headings (.H or HU) {4.2, 4.3} can occur within displays or footnotes. 

7.1 Static Displays 

.DS [format], [fill] [rindent] 
one or more lines of text 
.DE 
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A static display is sttrted by the JDS macro and terminated by the .DE macro. With no arguments DS 
accepts lines of text exactly as typed (no-fill mode) and will not indent lines from the prevailing left margin 
indentation or from the right margin. 

• The format argument is an integer or letter used to control the left margin indentation and centering 
with the following meanings: 


format 

Meaning 

m m 

no indent 

0 or L 

no indent 

1 or I 

indent by standard amount 

2 or C 

center each line 

3 or CB 

center as a block 

omitted 

no indent 


The fill argument is an integer or letter and can have the following meanings: 


fill 

Meaning 

M M 

no-fill mode 

0 or N 

no-fill mode 

lor F 

fill mode 

omitted 

no-fill mode 


• The rindent argument is the number of characters that the line length should be decreased, i.e, an in¬ 
dentation from the right margin. This number must be unsealed in the nroff formatter and is treated 
as ens. It may be scaled in the troff formatter or else defaults to e ms 

The standard amount of static display indentation is taken from the Si register, a default value of five spac¬ 
es. Thus, text of an indented display aligns with the first line of indented paragraphs, whose indent is contained 
in the Pi register (4.1). Even though their initial values are the same (default values), these two registers are 
independent. 


The display format argument value 3 (or CB) centers (horizontally) the entire display as a block (as opposed 
to DS 2 and .DF 2 which center each line individually). All collected lines are left justified, and the display is 
centered based on width of the longest line. This format must be used in order for the eqn/neqn “mark” and 
“lineup” feature to work with centered equations (7.4). 

By default, a blank line (one-half a vertical space) is placed before and after static and floating displays. 
These blank lines before and after static displays can be inhibited by setting the register Ds to 0. 


The following example shows usage of all three arguments for static displays. This block of text will be in¬ 
dented five spaces from the left margin, filled, and indented five spaces from the right margin (Le„ centered). 
The input text 

.DS I F 5 

"We the people of the United States, 

in order to form a more perfect union, 

establish justice, ensure domestic tranquillity, 

provide for the common defense, 

and secure the blessings of liberty to 

ourselves and our posterity, 

do ordain and establish this Constitution for the 
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United States of America.” 
.DE 


produces 


"We the people of the United States, in order to form a more perfect union, establish justice, 
ensure domestic tranquillity, provide for the common defense, and secure the blessings of liberty 
to ourselves and our posterity, do ordain and establish this Constitution to the United States of 
America.” 


7.2 Floating Displays 

.DF [format! [fill] [rindent] 
one or more lines of text 
.DE 

A floating display is started by the «DF macro and terminated by the .DE macro. Arguments have the sami 
meanings as static displays described above, except indent, no indent, and centering are calculated with respeci 
to the initial left margin. This is because prevailing indent may change between the time the formatter first 
reads the floating display and when the display is printed. One blank line (one-half a vertical space) occurs be¬ 
fore and after a floating display. 

The user may exercise precise control over the output positioning of floating displays through the use of 
two number registers, De and Df (see below). When a floating display is encountered by the nroff or trof; 
formatter, it is processed and placed onto a queue of displays waiting to be output. Displays are removed from 
the queue and printed in the order entered, which is the order they appeared in the input file. If a new floating 
display is encountered and the queue of displays is empty, the new display is a candidate for immediate output 
on the current page. Immediate output is governed by size of display and the setting of the Df register code. 
The De register code controls whether text will appear on the current page after a floating display has been 
produced. 

As long as the display queue contains one or more displays, new displays will be automatically entered there, 
rather than being output When a new page is started (or the top of the second column when in 2-column mode)’, 
the next display from the queue becomes a candidate for output if the Df register code has specified “top-of- 
page” output When a display is output it is also removed from the queue. 

When the end of a section (using section-page numbering) or the end of a document is reached, all displays 
are automatically removed from the queue and output This occurs before a .SG, .CS, or .TC macro is processed. 

A display will fit on the current page if there is enough room to contain the entire display or if the display 
is longer than one page in length and less than half of the current page has been used. A wide (full-page width) 
display will not fit in the second column of a 2-column document 

The De and Df number register code settings and actions are as follows: 

De Register 


CODE 


ACTION 


0 


No special action occurs (also the default condition). 
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COM ACTION 

1 A page eject will always follow the output of each floating display, so only one floating display 

will appear on a page and no text will follow it. 

Note: For any other code, the action performed is the same as for code 1. 

Df Register 

COM ACTION 

0 Floating displays will not be output until end of section (when section-page numbering) or 

end of document. 

1 Output new floating display on current page if there is space; otherwise, hold it until end of 

section or document 


2 

3 

4 


Output exactly one floating display from queue to the top of a new page or column (when in 
2-column mode). 


Output one floating display on current page if there is space; otherwise, output to the top of 
a new page or column. 


Output as many displays as will fit (at least one) starting at the top of a new page or column. 


Note: If De register is set to 1, each display will be followed by a page eject causing a new top of page 
to be reached where at least one more display will be output (this also applies to code 5). 

5 Output a new floating display on the current page if there is room (also the default condition). 

Output as many displays (at least one) as will fit on the page starting at the top of a new page 
or column. 


Note: For any code greater than 5, the action performed is the same as for code 5. 

The .WC macro {12.4} may also be used to control handling of displays in double-column mode and to control 
the break in text before floating displays. 


7.3 Tablet 


.TS [H] 

global options; 
column descriptors, 
title lines 


[•TH [N]] 

data within the table. 
.TE 


The .TS (table start) and .TE (table end) macros make possible the use of the tbl(l) program. These macros 
are used to delimit text to be examined by tbl and to set proper spacing around the table. The display function 
and the tbl delimiting function are independent In order to permit the user to keep together blocks that contain 
any mixture of tables, equations, filled text unfilled text and caption lines, the .TS/.TE block should be enclosed 
within a display (.DS/.DE). Floating tables may be enclosed inside floating displays (.DF/.DE). 


Macros .TS and .TE permit processing of tables that extend over several pages. If a table heading is needed 
for each page of a multipage table, the “H” argument should be specified to the .TS macro as above. Following 
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the options and format information, table title is typed on as many lines as required and is followed by the .TH 
macro. The .TH macro must occur when “.TS H” is used for a multipage table. This is not a feature of tbl but 
of the definitions provided by the MM macro package. 

The .TH (table header) macro may take as an argument the letter N. This argument causes the table header 
to be printed only if it is the first table header on the page. This option is used when it is necessary to build 
long tables from smaller .TS H/.TE segments. For example: 


.TS H 

global options; 

column descriptors. 

Title lines 

.TH 

data 

.TE 

.TS H 

global options; 

column descriptors. 

Title lines 

.TH N 

data 

.TE 


will cause the table heading to appear at the top of the first table segment and no heading to appear at the top 
of the second segment when both appear on the same page. However, the heading will still appear at the top 
of each page that the table continues onto. This feature is used when a single table must be broken into segments 
because of table complexity (e.g., too many blocks of filled text). If each segment had its own .TS H/.TH se¬ 
quence, it would have its own header. However, if each table segment after the first uses .TS H/.TH N, the table 
header will appear only at the beginning of the table and the top of each new page or column that the table con¬ 
tinues onto. 

For the nroff formatter, the -e option [-E for mm(l) {2.1}] may be used for terminals, such as the 450, 
that are capable of finer printing resolution. This will cause better alignment of features such as the lines form¬ 
ing the corner of a box. The -e is not effective with coJ(l). 


7.4 Equations 


.DS 

.EQ [label] 
equation(s) 


.EN 

.DE 


Mathematical typesetting programs eqn(l) and neqn expect to use the .EQ (equation start) and .EN (equa¬ 
tion end) macros as delimiters in the same way that tbl(l) uses .TS and .TE; however, .EQ and .EN must occur 
inside a .DS/.DE pair. There is an exception to this rule — if .EQ and .EN are used to specify only the delimiters 
for in-line equations or to specify eqn/neqn defines, the .DS and .DE macros must not be used; otherwise, extra 
blank lines will appear in the output 

The .EQ macro takes an argument that will be used as a label for the equation. By default, the label will 
appear at the right margin in the “vertical center” of the general equation. The Eq register may be set to 1 to 
change labeling to the left margin. 

The equation will be centered for centered displays; otherwise, the equation will be adjusted to the opposite 
margin from the label. 
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7.S Figurt, Table, Equation, and Exhibit Titles 

.FG (title] [override] [flag] 

.TB [title] [override] [flag] 

.EC [title] [override] [flag] 

.EX [title] [override] [flag] 

The JFG (figure title), .TB (table title), .EC (equation caption), and .EX (exhibit caption) macros are nor¬ 
mally used inside .DS/.DE pairs to automatically number and title figures, tobies, and equations. These macros 
use registers Fg, Tb, Ec, and Ex, respectively (see paragraph {2.4} on -rN5 to reset counters in sections). For 
example: 

.FG " This is a Figure Title " 


\ 


yields 


Figure 1. 


This is a Figure Title 


The .TB macro replaces “Figure” with “TABLE", the .EC macro replaces “Figure” with "Equation”, and 
the .EX macro replaces "Figure” with "Exhibit". The output title is centered if it can fit on a single line; other¬ 
wise, all lines but the first are indented to line up with the first character of the title. The format of the numbers 
may be changed using the .af request of the formatter. The format of the caption may be changed from 


Figure 1. Title 


to 


Figure 1—Title 


by setting the Of register to 1. 


The override argument is used to modify normal numbering. If flag argument is omitted or 0, override is 
used as a prefix to the number, if the flag argument is 1 , override is used as a suffix; and if the flag argument 
is 2, override replaces the number. If -rN5 {2.4} is given, "section-figure” numbering is set automatically and 
user-specified override string is ignored. 


As a matter of formatting style, table headings are usually placed above the text of tables, while figure, 
equation, and exhibit titles are usually placed below corresponding figures and equations. 


7.6 List of Rgurot, Tables, Equations, and Exhibits 

A list of figures, tables, exhibits, and equations are printed following the table of contents if the number 
registers Lf, Lt, Lx, and Le (respectively) are set to 1. The Lf Lt, and Lx registers are 1 by default; Le is 0 bv 
default 

Titles of these lists may be changed by redefining the following strings which are shown here with their 
default values: 


.ds Lf LIST OF FIGURES 
.ds Lt LIST OF TABLES 
.ds Lx LIST OF EXHIBITS 
.ds Le LIST OF EQUATIONS 
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8. Footnotes 


There are two macros (.FS and .FE) that delimit text of footnotes, a string that automatically numbers foot¬ 
notes, and a macro (.FD) that specifies the style of footnote text. Footnotes are processed in an environment 
different from that of the body of text. Refer to ,ev request. 

8.1 Automatic Numbering of Footnotes 

Footnotes may be automatically numbered by typing the three characters “\*F” (i.e., invoking the string 
P immediately after the text to be footnoted without any intervening spaces. This will place the next sequential 
footnote number (in a smaller point size) a half line above the text to be footnoted. 

8.2 Dolimiting Footnote Text 

.FS [label] 

one or more lines of footnote text 

.FE 

There are two macros that delimit the text of each footnote. The .FS (footnote start) macro marks the begin¬ 
ning of footnote text, and the .FE (footnote end) macro marks the end. The label on the .FS, if present, will be 
used to mark footnote text. Otherwise, the number retrieved from the string Fwill be used. Automatically num¬ 
bered and user-labeled footnotes may be intermixed. If a footnote is labeled (.FS label), the text to be footnoted 
must be followed by label, rather than by “\*F”. Text between .FS and .FE is processed in fill mode. Another 
.r b, a .DS, or a -OF are not permitted between .FS and .FE macros. If footnotes are required in the title, abstract, 
or table {7.3} only labeled footnotes will appear properly. Everywhere else automatically numbered footnotes 
work correctly. For example: 

Automatically numbered footnote: 

This is the line containing'the word\*F 

.FS 

This is the text of the footnote. 

.FE 

to be footnoted. 

Labeled footnote: 

This is a labeled* 

.FS * 

The footnote is labeled with an asterisk. 

.FE 

footnote. 


Text of the footnote (enclosed within the .FS/.FE pair) should immediately follow the word to be footnote 
m the input text, so that “\*F” or label occurs at the end of a line of input and the next line is the .FS maci 
call. It is also good practice to append an unpaddable space {3.3} to “\*F” or label when they follow an end-oi 
sentence punctuation mark (i.e., period, question mark, exclamation point). 


Figure 4.2 illustrates the various available footnote styles as well as numbered and labeled footnotes. 

8.3 Format Style of Footnote Text 

•FD [arg] [1] 
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Within footnote text, the user can control formatting style by specifying text hyphenation, right margin 
justification, and text indentation, as well as left or right justification of the label when text indenting is used. 
The JD macro is invoked to select the appropriate style. 

The first argument is a number from the left column of the following table. Formatting style for each num¬ 
ber is indicated in the remaining four columns. Further explanation of the first two of these columns is given 
in the definitions of the .ad, .hy, jia, and .nh (adjust, hyphenation, no adjust, and no hyphenation, respectively) 
requests in the nroff part of this document. 


33. 

HYPHENATION 

ADJUST 

TEXT 

INDENT 

LAB& 

JUSTIFICATION 

0 

.nh 

.ad 

yes 

left 

1 

•hy 

.ad 

yes 

left 

2 

.nh 

.na 

yes 

left 

3 

•hy 

.na 

yes 

left 

4 

.nh 

.ad 

no 

left 

5 

.hy 

.ad 

no 

left 

6 

.nh 

.na 

no 

left 

7 

.hy 

.na 

no 

left 

8 

.nh 

.ad 

yes 

right 

9 

•hy 

.ad 

yes 

right 

10 

.nh 

.na 

yes 

right 

11 

.hy 

.na 

yes 

right 


If the argument to .FD is greater than 11, the effect is as if “.FD 0” were specified. If the first argument 
is omitted or null, the effect is equivalent to “.FD 10” in the nroff formatter and to “.FD 0” in the troff 
formatter, these are also the respective initial default values. 

If the second argument is specified, then when a first-level heading is encountered, automatically numbered 
footnotes begin again with 1. This is most useful with the “section-page” page numbering scheme. As an exam¬ 
ple, the input line 

.FD"" 1 

maintains the default formatting style and causes footnotes to be numbered afresh after each first-level heading 
in a document. 

Hyphenation across pages is inhibited by MM except for long footnotes that continue to the following page. 
If hyphenation is permitted, it is possible for the last word on the last line on the current page footnote to be 
hyphenated. The user has control over this situation by specifying an even .FD argument. 

Footnotes are separated from the body of the text by a short line rule. Those that continue to the next page 
are separated from the body of the text by a full-width rule. In the troff formatter, footnotes are set in type 
two points smaller than the point size in the body of text. 

8.4 Spacing Between Footnote Entries 

Normally, one blank line (a 3-point vertical space) separates footnotes when more than one occurs on a page. 
To change this spacing, the Fs number register is set to the desired value. For example: 

.nr Fs 2 

will cause two blank lines (a 6-point vertical space) to occur between footnotes. 
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9. Pag* Headers and Footers 

Text printed at the top of each page is called page header. Text printed at the bottom of each page is called 
page footer There can be up to three lines of text associated with the header — every page, even page only, and 
odd page only. Thus the page header may have up to two lines of text — the line that occurs at the top of every 
page and the line for the even- or odd-numbered page. The same is true for the page footer. 

This part describes the default appearance of page headers and page footers and ways of changing them. 
The term header (not qualified by even or odd) is used to mean the page header line that occurs on every page, 
and similarly for the term footer 

9.1 Default Headers and Footers 

By default, each page has a centered page number as the header. There is no default footer and no even/odd 
default headers or footers except as specified in paragraph {9.3}. 

In a memorandum or a released-paper style document, the page header on the first page is automatically 
suppressed provided a break does not occur before the .MT macro is called. Macros and text in the following 
categories do not cause a break and are permitted before the memorandum types (.MT) macro: 

e Memorandum and released-paper style document macros (.TL, .AU, .AT, .TM, .AS, .AE, .OK, .ND, .AF, 
.NS, and JIE) 

e Page headers and footers macros (.PH, .EH, .OH, .PF, .EF, and .OF) 
e The .nr and .ds requests. 

9.2 Header and Footer Macros 

For header and footer macros (.PH .EH, .OH, .PF, .EF, and .OF), the argument [arg] is of the following form: 
" ’left-part’center-part’right-part’" 

If it is inconvenient to use apostrophe (’) as the delimiter because it occurs within one of the parts, it may be 
replaced uniformly by any other character. In formatted output, the parts are left justified, centered, and right 
justified, respectively. 

9.2.1 Page Header 

.PH (arg] 

The .PH macro specif es the header that is to appear at the top of every page. The initial value is the default 
centered page number enclosed by hyphens. The page number contained in the P register is an Arabic number. 
The format of the number may be changed by the .af macro request. 

If “debug mode ”is set using the flag —rDl on the command line {2.4}, additional information printed at the 
top left of each page is included in the default header. This consists of the Source Code Control System (SCCS) 
release and level of MM (thus identifying the current version {12.3}) followed by the current line number within 
the current input file. 

9.2.2 Even-Page Header 

.EH {arg] 
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The .EH macro supplies a line to be printed at the top of each even-numbered page immediately following 
the header. Initial value is a blank line. 

9.2.3 Odd-Page Header 

.OH [arg] 

The .OH macro is the same as the .EH except that it applies to odd-numbered pages. 


9.2.4 Poge Footer 

•PF [arg] 

The .PF macro specifies the line that is to appear at the bottom of each page. Its initial value is a blank 
line. If the -rCn flag is specified on the command line [2.4], the type of copy follows the footer on a separate 
line. In particular, if -rC3 or -rC4 (DRAFT) is specified, the footer is initialized to contain the date {6.8} instead 
of being a blank line. 

9.2.5 Even-Poge Footer 

.EF [arg] 

The .EF macro supplies a line to be printed at the bottom of each even-numbered page immediately preced¬ 
ing the footer. Initial value is a blank line. 

9.2.6 Odd-Pogo Footer 

.OF [arg] 


The .OF macro is the same as .EF except that it applies to odd-numbered pages. 

9.2.7 First Page Footer 


By default, the first page footer is a blank line. If, in the input text file, the user specifies .PF and/or .OF 
before the end of the first page of the document, these lines will appear at the bottom of the first page. 


The header (whatever its contents) replaces the footer on the first page only if the -rNl flag is specified 
on the command line {2.4}. 


9.3 Default Header and Footer With Section-Page Numbering 

Pages can be numbered sequentially within sections by “section-number page-number” [4.5]. To obtain this 
numbering style, -rN3 or -rN5 is specified on the command line. In this case, the default footer is a centered 
“section-page” number, e.g., 7-2; and the default page header is blank. 


9.4 Strings and Registers in Header and Footer Macros 


String and register names may be placed in arguments to header and footer macros. If the value of the string 
or register is to be computed when the respective header or footer is printed, invocation must be escaped by 
four backslashes. This is because string or register invocation will be processed three times: 


1. As the argument to the header or footer macro 

2. In a formatting request within the header or footer macro 
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3. In a .tl request during header or footer processing. 

For example, page number register P must be escaped with four backslashes in order to specify a header 
in which the page number is to be printed at the right margin, e.g.: 

.PH" "’Page \\\\nP’" 

creates a right-justified header containing the word “Page” followed by the page number. Similarly, to specify 
a footer with the “section-page” style, the user specifies (see paragraph {4.2.2^} for meaning of Hi): 

•PF" W\\n(Hl-\\\\nP " 

If the user arranges for the string a] to contain the current section heading which is to be printed at the 
bottom of each page, the .PF macro call would be: 

•PF " ”\\\\*(a]” " 

If only one or two backslashes were used, the footer would print a constant value for a], namely, its value 
when .PF appeared in the input text 

9.5 Htodir and Footer Exampio 

The following sequence specifies blank lines for header and footer lines, page numbers on the outside margin 
of each page (i.e., top left margin of even pages and top right margin of odd pages), and “Revision 3” on the 
top inside margin of each page (nothing is specified for the center): 

PH"" 

PF"" 

.EH " \\\\nP”Revision 3'" 

.OH " 'Revision 3’\\\\nP’ - 

9.6 Generalized Top-of-Page Processing 


Note: This part is intended only for users accustomed to writing formatter macros. 

During header processing, MM invokes two user-definable macros: 
e The .TP (top of page) macro is invoked in the environment (refer to .ev request) of the header. 


e The -PX is a page header user-exit macro that is invoked (without arguments) when the normal environ 
ment has been restored and with the “no-space” mode already in effect. 


The effective initial definition of .TP (after the first page of a document) is 

.de TP 
.sp 3 
•tl W(Jt 
Jf e ’tl \\*(}e 
if o ’tl \\*(}o 

•Sp 2 


Ihh nS"? lt . contai ° s _ th ® h e ad er. the string (e contains the even-page header, and the string Jo contains the 
odd-page header as defined by the .PH, .EH, and .OH macros, respectively. To obtain more specialized page ti¬ 
tles, the user may redefine the .TP macro to cause the desired header processing {12.5}. Formatting done within 
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the .TP macro is processed in an environment different from that of the body. For example, to obtain a page 
header that includes three centered lines of data, i.e., document number, issue date, and revision date, the user 
could define the .TP as follows: 

.de TP 
.sp 
.ce 3 

777-888-999 
Iss. 2, AUG 1977 
Rev. 7, SEP 1977 
.sp 

The .PX macro may be used to provide text that is to appear at the top of each page after the normal header 
and that may have tab stops to align it with columns of text in the body of the document. 

9.7 Generalized Bottom-of-Page Processing 

.BS 

zero or more lines of text 
.BE 

Lines of text that are specified between the .BS (bottom-block start) and .BE (bottom-block end) macros 
will be printed at the bottom of each page after the footnotes (if any) but before the page footer. This block of 
text is removed by specifying an empty block, i.e.: 

.BS 

.BE 

The bottom block will appear on the table of contents, pages, and the cover sheet for memorandum for file, but 
not on the technical memorandum or released-paper cover sheets. 

9.8 Top and Bottom (Vortical) Margins * 

.VM (top] [bottom] 

The .VM (vertical margin) macro allows the user to specify additional space at the top and bottom of the 
page. This space precedes the page header and follows the page footer. The .VM macro takes two unsealed argu¬ 
ments that are treated as v’s. For example: 

• .VM 10 15 

adds 10 blank lines to the default top of page margin and 15 blank lines to the default bottom of page margin. 
Both arguments must be positive (default spacing at the top of the page may be decreased by redefining .TP). 

9.9 Proprietary Marking 

.PM [code] 

The .PM (proprietary marking) macro appends to the page footer a PRIVATE, NOTICE, BELL LABORA¬ 
TORIES PROPRIETARY, or BELL LABORATORIES RESTRICTED disclaimer. The code argument may be: 

code Disclaimer 

none turn off previous disclaimer, if any 
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code Disclaimer 

P PRIVATE 

N NOTICE 

BP BELL LABORATORIES PROPRIETARY 

BR BELL LABORATORIES RESTRICTED 

hv are iD a f0rm a PP roved for ose by the Bell System. The user may alternate disclaimers 

by use of the .BS/.BE macro pair. 


9.10 Private Documents 
.nr Pv value 


I he prin . ted ’ entered, and underlined on the second line of a document (preceding 

the page header). This is done by setting the Pv register value : 


value Meaning 

0 do not print PRIVATE (default) 

1 PRIVATE on first page only 

2 PRIVATE on all pages 


“DDn;?ic"' IS ^ ® USer definabIe - Tp macro may not be used because the .TP macro is used by 

rKiVATE on all pages except the first page of a memorandum on which .TP is not invoked. 

10. Table of Contents and Cover Sheet 


MM to print 


The table of contents and the cover sheet for a document are produced by invoking the .TC and CS macros 
respectively. * 


Note: This section refers to cover sheets for technical memoranda and released papers only. The mecha- 
nism for producing a memorandum for file cover sheet was discussed earlier {6.5}. 

.. Tb f® e , macros normally appear once at the end of the document, after the Signature Block {6.11.11 and Nota- 
tions {6.11.2} macros, and may occur in either order. 


The table of contents is produced at the end of the document because the entire document must be processed 
ore the table of contents can be generated. Similarly, the cover sheet may not be desired by a user and is 
therefore produced at the end. 

10.1 Table of Contents 


-TC [slevel] [spacing] [tlevel] [tab] [headl] [head2] [head3] [head4] [head5] 

The macro generates a table of contents containing heading levels that were saved for the table of con¬ 
tents as determined by the value of the Cl register [4.4j. Arguments to .TC control spacing before each entry 

wordXOhTrSTO 1 ’^ 611 Page nUmber ’ aDd additional text on the first Page of the table of contents before the’ 

Spacing before each entry is controlled by the first and second arguments ([slevel] and [spacing]). Headings 
whose level is less than or equal to slevel will have spacing blank lines (halves of a vertical space) before them. 
Both slevel and spacing default to 1. This means that first-level headings are preceded by one blank line (one- 
half a vertical space). The slevel argument does not control what levels of heading have been saved; saving of 
headings is the function of the Cl register. 
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The third and fourth arguments ([CieveT] and [tab] control placement of associated page number for each 
heading. Page numbers can be justified at the right margin with either blanks or dots (called leaders) separating 
the heading text from the page number, or the page numbers can follow the heading text. 

For headings whose level is less than or equal to tlevel (default 2), page numbers are justified at the right 
margin. In this case, the value of tab determines the character used to separate heading text from page number. 
If tab is 0 (default value), dots (i.e., leaders) are used. If tab is greater than 0, spaces are used. 

For headings whose level is greater than tlevel page numbers are separated from heading text by two spaces 
(i.e., page numbers are “ragged right”, not right justified). 

Additional arguments ([ headl) ... [hea,d5\) are horizontally centered on the page and precede the table of 
contents. 

If the .TC macro is invoked with at most four arguments, the user-exit macro .TX is invoked (without argu¬ 
ments) before the word “CONTENTS” is printed, or the user-exit macro .TY is invoked and the word “CON¬ 
TENTS” is not printed. 

By defining .TX or .TY and invoking .TC with at most four arguments, the user can specify what needs to 
be done at the top of the first page of the table of contents. For example: 

.de TX 
.ce 2 

Special Application 
Message Transmission 
.sp 2 
.in +10n 
Approved: \T3i’ 

.in 

-sp 

.TC 

yields the following output when the file is formatted 

Special Application 
Message Transmission 

Approved:__ — 


CONTENTS 


If the .TX macro were defined as .TY, the word “CONTENTS" would be suppressed. Defining .TY as an 
empty macro will suppress “CONTENTS” with no replacement: 

.deTY 


By default, the first level headings will appear in the table of contents left justified. Subsequent levels will 
be aligned with the text of headings at the preceding level. These indentations may be changed by defining the 
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Ci string which takes a maximum of seven arguments corresponding to the heading level*. It must be given at 
least as many arguments as are set by the Cl register. Arguments must be scaled; for example, with “C7 - 5": 

.ds Ci .25i .5i .75i li li 


or 


.ds Ci 0 2n 4n 6n 8n 

• 

Two other registers are available to modify the format of the table of contents — Oc and Cp. By default, 
table of contents pages will have lowercase Roman numeral page numbering. If the Oc register is set to 1, the 
.TC macro will not print any page number but will instead reset the P register to 1. It is the user’s responsibility 
to give an appropriate page footer to specify the placement of the page number. Ordinarily, the same .PF macro 
(page footer) used in the body of the document will be adequate. 

The list of figures, tables, etc. pages will be produced separately unless Cp is set to 1, which causes these 
lists to appear on the same page as the table of contents. 

10.2 Cover Sheet 

.CS [pages] [other] [total] [figs] [tbls] [refs] 

The .CS macro generates a cover sheet in either the released paper or technical memorandum style (see 
paragraph [6.5] for details of the memorandum for file cover sheet). All other information for the cover sheet 
is obtained from data given before the .MT macro call {6.1}. If the technical memorandum style is used, the .CS 
macro generates the “Cover Sheet for Technical Memorandum”. The data that appear in the lower left corner 
of the technical memorandum cover sheet (counts of: pages of text, other pages, total pages, figures, tables, and 
references) are generated automatically (0 is used for “other pages”). These values may be changed by supplying 

the corresponding arguments to the .CS macro. If the released-paper style is used, all arguments to CS are ig¬ 
nored. 6 

11 • Ref er*nc*s 


There are two macros (.RS and .RF) that delimit the text of references, a string that automatically numbers 
the subsequent references, and an optional macro (.RP) that produces reference pages within the document 

11.1 Automatic Numbering of References 

Automatically numbered references may be obtained by typing \*(Rf (invoking the string Rf) immediately 
after the text to be referenced.This places the next sequential reference number (in a smaller point size) en¬ 
closed in brackets one-half line above the text to be referenced. Reference count is kept in the R/number regis- 


11.2 Delimiting Reference Text 

.RS [string-name] 

.RF 

The JtS and JRF macros are used to delimit text of each reference as shown below: 

A line of text to be referenced.\*(Rf 
.RS 

reference text 
.RF 
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11.3 Subsequent References 

The .RS macro takes one argument, a string-name For example: 

.RS aA 

reference text 
.RF 

The string aA is assigned the current reference number. This string may be used later in the document as 
the string call, \*(aA, to reference text which must be labeled with a prior reference number. The reference 
is output enclosed in brackets one-half line above the text to be referenced. No .RS/.RF pair is needed for subse¬ 
quent references. 

11.4 Reference Poge 

.RP [argl] [arg2] 

A reference page, entitled by default “References”, will be generated automatically at the end of the docu¬ 
ment (before table of contents and cover sheet) and will be listed in the table of contents. This page contains 
the reference items (i.e., reference text enclosed within .RS/.RF pairs). Reference items will be separated by 
a space (one-half a vertical space) unless the Ls register is set to 0 to suppress this spacing. The user may change 
the reference page title by defining the Rp string: 

.ds Rp " New Title " 

The JRP (reference page) macro may be used to produce reference pages anywhere else within a document 
(i.e., after each major section). It is not needed to produce a separate reference page with default spacings at 
the end of the document 

Two .RP macro arguments allow the user to control resetting of reference numbering and page skipping. 
. argl Meaning 

0 reset reference counter (default) 

1 do not reset reference counter 

arg2 Meaning 

0 put on separate page (default) 

1 do not cause a following .SK 

2 do not cause a preceding .SK 

3 no .SK before or after 

If no .SK is issued by the .RP macro, a single blank line will separate the references from the following/ 
preceding text The user may wish to adjust spacing. For example, to produce references at the end of each major 
section: 

.sp 3 

.RP l 2 

.HI" Next Section " 

12. Miscellaneous Features 
12.1 Bold, Italic, and Roman Fonts 

.B [bold-arg] [previous-font-arg] ... 
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.1 [italic-arg] [previous-font-are] 
.R 


When called without arguments, the .B macro changes the font to bold and the .1 macro changes to underlin¬ 
ing (italic). This condition continues until the occurrence of the .R macro which causes the Roman font to be 
restored. Thus: 


J 

here is some text. 

.R 

yields underlined text via the nroff and italic text via the troff(l) formatter. 

If the .B or .1 macro is called with one argument, that argument is printed in the appropriate font (under¬ 
lined in the nroff formatter for .1). Then the previous font is restored (underlining is turned off in the nroff 
formatter). If two or more arguments (maximum six) are given with a .B or .1 macro call, the second argument 
is concatenated to the first with no intervening space (1/12 space if the first font is italic) but is printed in the 
previous font Remaining pairs of arguments are similarly alternated. For example: 

J italic " text" right-justified 


produces 

italic text right -justified 

The .B and .1 macros alternate with the prevailing font at the time the macros are invoked. To alternate 
specific pairs of fonts, the following macros are available: 

•IB .BI .IR .RI .RB .BR 

Each macro takes a maximum of six arguments and alternates arguments between specified fonts. 

When using a terminal that cannot underline, the following can be inserted at the beginning of the document 
to eliminate all underlining: 

.rm ul 
.rm cu 


Note: Font changes in headings are handled separately (4.2.2.4.1J. 

12.2 Justification of Right Margin 
.SA [arg] 


The .SA macro is used to set right-margin justification for the main body of text. Two justification flags 
!5 e an L d d * f * ult The “SA 0” call sets both flags to no justification: it acts like the .na request 

I he .SA 1 call sets both flags to cause both right and left justification, the same as the .ad request. Howeve- 
calling .SA without an argument causes the current flag to be copied from the default flag, thus performing 
either a .na or .ad depending on the default Initially, both flags are set for no justification in the nroff 
formatter and for justification in the troff formatter. 


In general, the no adjust request (.na) can be used to ensure that justification is turned off, but .SA should 
be used to restore justification, rather than the .ad request. In this way, justification or no justification for the 
remainder of the text is specified by inserting “.SA 0” or “.SA 1” once at the beginning of the document. 
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12.3 SCCS Release Identification 

The RE string contains the SCCS release and the MM text formatting macro package current version level. 
For example: 

This is version \*(RE of the macros. 

produces 

This is version 10.129 of the macros. 

This information is useful in analyzing suspected bugs in MM. The easiest way to have the release identifica¬ 
tion number appear in the output is to specify -rDl {2.4} on the comipand line. This causes the RE string to 
be output as part of the page header {9.2.1}. 

12.4 Two-Column Output 

.2C 

text and formatting requests (except another 2C ) 

.1C 

The MM text formatting macro package can format two columns on a page. The ,2C macro begins 2-column 
processing which continues until a .1C macro (1-column processing) is encountered. In 2-column processing, 
each physical page is thought of as containing 2-columnar “pages” of equal (but smaller) “page” width. Page 
headers and footers are not affected by 2-column processing. The 2C macro does not balance 2-column output. 

It is possible to have full-page width footnotes and displays when in 2-column mode, although default action 
is for footnotes and displays to be narrow in 2-column mode and wide in 1-column mode. Footnote and display 
width is controlled by the .WC (width control) macro, which takes the following arguments: 

arg Meaning 

N Default mode (-WF, -FF, —WD, FB). 

WF Wide footnotes (even in 2-column mode). 

-WF DEFAULT: Turn off WF. Footnotes follow column mode; wide in 1-column mode (1C), narrow 

in 2-column mode (2C), unless FF is set. 

FF First footnote. All footnotes have same width as first footnote encountered for that page. 

-FF DEFAULT: Turn off FF. Footnote style follows settings of WF or -WF. 

WD Wide displays (even in 2-column mode). 

-WD DEFAULT: Displays follow the column mode in effect when display is encountered. 

FB DEFAULT: Floating displays cause a break when output on the current page. 

—FB Floating displays on current page do not cause a break. 

Note: The “.WC WD FF” command will cause all displays to be wide and all footnotes on a page to be 
the same width while “.WC N” will reinstate default actions. If conflicting settings are given to .WC, the 
last one is used. A ".WC WF -WF” command has the effect of a “.WC -WF”. 
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12.5 Column Headings for Two-Column Output 

Note: This section is intended only for users accustomed to writing formatter macros. 

In 2-column processing output, it is sometimes necessary to have headers over each column, as well as head¬ 
ers over the entire page. This is accomplished by redefining the .TP macro {9.6} to provide header lines both for 
the entire page and for each of the columns. For example: 

.de TP 
.sp 2 

.tl ’Page \\nP*OVERALL" 

.tl "TITLE” 

.sp 

.nf 

,ta 16C 31R 34 50C 65R 
left(Bcenter<I)right(I)left([>c$nter<I> right 
<5first column<5(D<Dsecond column 
ii 

.sp 2 

where <5 stands for the tab character. 

The above example will produce two lines of page header text plus two lines of headers over each column. 
Tab stops are for a 65-en overall line length. 

12.6 Vertical Spacing 

.SP [lines] 

There exists several ways of obtaining vertical spacing, all with different effects. The .sp request spaces 
the number of lines specified unless the no space (.ns) mode is on, then the .sp request is ignored. The no space 
mode is set at the end of a page header to eliminate spacing by a .sp or .bp request that happens to occur at 
the top of a page. This mode can be turned off by the .rs (restore spacing) request. 

The .SP macro is used to avoid the accumulation of vertical space by successive macro calls. Several .SP 
calls in a row will not produce the sum of the arguments but only the maximum argument. For example, the 
following produces only three blank lines: 

.SP 2 
.SP 3 
.SP 

Many MM macros utilize .SP for spacing. For example, “JL.E 1” {5.1.3} immediately followed by “.P” {4.1} pro¬ 
duces only a single blank line (one-half a vertical space) between the end of the list and the following paragraph. 
An omitted argument defaults to one blank line (one vertical space). Negative arguments are not permitted. 
The argument must be unsealed but fractional amounts are permitted. The .SP macro (as well as .sp) is also 
inhibited by the j»s request. 

12.7 Skipping Pages 

.SK [pages] 

The .SK macro skips pages but retains the usual header and footer processing. If the pages argument is 
omitted, null, or 0, .SK skips to the top of the next page unless it is currently at the top of a page (then it does 
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nothing). The “.SK n" skips n pages. The .SK macro always positions text that follows it at the top of a page, 
while ".SK 1” always leaves one page blank except for the header and footer. 

12.8 Forcing on Odd Pogo 

.OP 

The .OP macro is used to ensure that formatted output text following the macro begins at the top of an 
odd-numbered page. If currently at the top of an odd-numbered page, text output begins on that page (no motion 
takes place). If currently on an even page, text resumes printing at the top of the next page. If currently on an 
odd page (but not at the top of the page), one blank page is produced, and printing resumes on the next odd- 
numbered page after that. 

12.9 Setting Point Size and Vertical Spacing 

.S [point size] [vertical spacing] 

In the troff formatter, the default point size (obtained from the MM register S [2.4]) is 10 points, and the 
vertical spacing is 12 points (six lines per inch). Prevailing point size and vertical spacing may be changed by 
invoking the .S macro. 

The mnemonics D (default value), C (current value), and P (previous value) may be used for both arguments. 

• If an argument is negative, current value is decremented by the specified amount. 

• If an argument is positive, current value is incremented by the specified amount. 

• If an argument is unsigned, it is used as the new value. 

• If there are no arguments, the .S macro defaults to P. 

• If the first argument is specified but the second is not, then (default) D is used for the vertical spacing. 

Default value for vertical spacing is always two points greater than the current point size. Footnotes {8} are two 
points smaller than the body with an additional 3-point space between footnotes. A null ( " " ) value for either 
argument defaults to C (current value). Thus, if n is a numeric value: 


.s 

«SPP 

.S"" n 

=.S C n 

.S n"" 

«.S n C 

.Sn 

=.S n D 

.S M " 

=.S C D 

g »» *» H H 

=.S CC 

.S n n 

=.S n n 


If the first argument is greater than 99, the default point size (10 points) is restored. If the second argument 
is greater than 99, the default vertical spacing (current point size plus two points) is used. For example: 

.S 100 =.S 10 12 

.S 14 111 =.S 14 16 

The .SM macro allows the user to reduce by one point the size of a string: 

.SM stringl [string2] [string3] 
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If the third argument is omitted, the first argument is made smaller and is concatenated with the second 

— " T la T S !E eCified - If 111 three arguments are P resent * «y are null), the second ar^ment 
is made smaller and all three arguments are concatenated. For example: * 


INPUT 

OUTPUT 

.SM X 

X 

.SM X Y 

XY 

.SM Y X Y 

YXY 

.SM YXYX 

YXYX 

.SM YXYX ) 

YXYX) 

•SM ( YXYX ) 

(YXYX) 

.SM Y XYX " " 

YXYX 


12.10 Producing Accents 

The following strings may be used to produce accents for letters: 



IltPUT 

OUTPUT 

Grave accent 

c\*' 

% 

c 

Acute accent 

♦\*' 

e 

Circumflex 

o\*‘ 

0 

Tilde 

n\*‘ 

ft 

Cedilla 

c\*. 

C 

Lower-case umlaut 

u\*: 

u 

Upper-case umlaut 

UV; 

0 


12.11 Inserting Text Interactively 


ilD [prompt] [diversion] [string] 

The JtD (read insertion) macro allows a user to stop the standard output of a document and to read text 
from the standard input until two consecutive newline characters are found. When newline characters are en¬ 
countered, normal output is resumed. 


• The prompt argument will be printed at the terminal. If not given, .RD signals the user with a BEL 
terminal output 


on 


• The ' diversion argument allows the user to save all text typed in after the prompt in a macro whose name 
is that of the diversion. 


• The string argument allows the user to save for later reference the first line following the prompt 
the named string. 


in 


The .RD macro follows the formatting conventions in effect. Thus, the following examples assume that the 
.KD is invoked m no-fill mode (jif): 


-RD Name aA bB 
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produces 

Name: J. Jones (user types name) 

16 Elm Rd., 

Piscataway 

The diverted macro .aA will contain 

J. Jones 
16 Elm Rd., 

Piscataway 

The string bB(\*bB) contains “J. Jones”. 

A newline character followed by an EOF (user specifiable CONTROL d) also allows the user to resume nor¬ 
mal output 

13. Errors and Debugging 

13.1 Error Terminations 

When a macro detects an error, the following actions occur: 
e A break occurs. 

e The formatter output buffer (which may contain some text) is printed to avoid confusion regarding loca- * 
tion of the error. 

e A short message is printed giving the name of the macro that detected the error, type of error, and ap¬ 
proximate line number in the current input file of the last processed input line. Error messages are ex¬ 
plained in Table 4.D. 

• Processing terminates unless register D {2.4} has a positive value. In the latter case, processing continues 
even though the output is guaranteed to be deranged from that point on. 

The error message is printed by outputting the message directly to the user terminal. If an output filter, 
such as 300(1), 450(1), or hp(l) is being used to post-process the nroff formatter output, the message may 
be garbled by being intermixed with text held in that filter’s output buffer. 

Note: If any of cw(l), eqn(l)/neqn, and tbl(l) programs are being used and if the -o list option of the 
formatter causes the last page of the document not to be printed, a harmless “broken pipe” message may 
result. 

13.2 Disappearance of Output 

Disappearance of output usually occurs because of an unclosed diversion (e.g., a missing .DE or .FE macro). 
Fortunately, macros that use diversions are careful about it, and these macros check to make sure that illegal 
nestings do not occur. If any error message is issued concerning a missing .DE or .FE, the appropriate action 
is to search backwards from the termination point looking for the corresponding associated .DF, .DS, or .FS 
(since these macros are used in pairs). 

The following command: 

grep -n ’~\.[EDFRT] [EFNQS]’ files ... 
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K?n“ **" ' DF ';?v S ’ ; DE ’ - EQ ; ? S - - PE - ' Ra RP •«. *»« -TE macro, found in tile,.... each preceded 
sion'or thesTmacroi^* "“ mber “ th *‘ file - Thl * li,tin « be used to check lor illegal nesting and/or omis- 


Extending and Modifying MM Macros 


14.1 Naming Convontions 

In this part, the following conventions are used to describe names: 
n: Digit 

a: Lowercase letter 
A: Uppercase letter 


r 

s: 


Any alphanumeric character (: a, n, A, or 1, ie., letter or digit) 
any nonalphanumeric character (special character) 


All other characters are literals (i.e., characters stand for themselves). 

Request, macro, and string names are kept by the formatters in a single internal table; therefore, there must 
be no duplication among such names. Number register names are kept in a separate table. 


14.1.1 Names Used by Formatters 

requests: aa (most common) 

an (only one, currently: c2) 
registers: aa (normal) 

jc (normal) 

.s (only one, currently: .$) 
a. (only one, currently: c.) 

% (page number) 

14.1.2 Names Used by MM 

macros and strings: A, AA, Aa (accessible to users; e.g., macros P and HU, strings F, BU, and Lt) 
nA (accessible to users; only two, currently: 1C and 2C) 
aA (accessible to users; only one, currently: nP) 
s (accessible to users; only the seven accents, currently {12.10}) 

)x, }x, ]x, >x, ?x (internal) 

registers: An, Aa (accessible to users; e.g., Hi, Fg) 

A (accessible to users; meant to be set on the command line; e.g., C) 

:x, pc, H, ?x, !x (internal) 
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14.1.3 Namti Used by CW, EQN/NEQN, and TBL Programi 

The cw(l) program is the constant-width font preprocessor for the troff formatter. It uses the following 
five macro names: 

.CD, .CN, .CP, .CW, and .PC. 

This preprocessor also uses the number register names cE and cW. Mathematical equation 
preprocessors, eqn(l) and neqn, use registers and string names of the form an. The table 
preprocessor, tbl(l), uses T&, Ti, and TW, and names of the form: 

a- a+ al nn na *a #a #s 

14.1.4 Nomas Defined by User 

Names that consist either of a single lowercase letter or a lowercase letter followed by a character other 
than a lowercase letter (names .c2 and .nP are already used) should be used to avoid duplication with already 
used names. The following is a possible naming convention: 

macros: aA (e.g., bG, kW) 

strings: as (e.g., c), f], p}) 

registers: a (e.g., f, t) 

14.2 Sample Extensions 

14.2.1 Appendix Headings 

The following is a way of generating and numbering appendix headings: 

.nr Hu 1 
.nr a 0 
.deaH 
.nr a +1 
.nr P 0 

.PH " Appendix \\na-\\\\\\\\nP' ” 

.SK 

.HU " \\$1" 


After the above initialization and definition, each call of the form .aH " title" begins a new page (with the 
page header changed to “Appendix a-n”) and generates an unnumbered heading of title, which, if desired, can 
be saved for the table of contents. Those who wish apppendix titles to be centered must, in addition, set the regis¬ 
ter He to 1 J4.2.2.3}. 

14.2.2 Hanging Indent With Tabs 

The following example illustrates the use of the hanging indent feature of variable-item lists {5.1.1.6}. A 
user-defined macro is defined to accept four arguments that make up the mark In the output, each argument 
is to be separated from the previous one by a tab; tab settings are defined later. Since the first argument may 
begin with a period or apostrophe, the “\&” is used so that the formatter will not interpret such a line as a 
formatter request or macro call. 

Note: The 2-character sequence “\&” is understood by formatters to be a “zero-width” space. It causes 
no output characters to appear, but it removes the special meaning of a leading period or apostrophe. 
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The \t is translated by the formatter into a tab. The “\c" is used to concatenate the input text that follows 
the macro call to the line built by the macro. The macro and an example of its use are: 

.de aX 
•LI 

\&\\$l\t\\$2\t\\$3\t\\$4\t\c 


.ta 8 14 20 24 
.VL 36 

.aX .nh off \- no 
No hyphenation. 

Automatic hyphenation is turned off. 

Words containing hyphens 

(e.g., mother-in-law) may still be split across lines. 

.aX .hy on \- no 

Hyphenate. 

Automatic hyphenation is turned on. 

.aX ,hc\<sp>c none none no 

Hyphenation indicator character is set to “c” or 

removed. 

During text processing, the indicator is suppressed 
.and will not appear in the output 
Prepending the indicator to a word has the effect 
of preventing hyphenation of that word. 

LE 

where <sp> stands for a space. 

The resulting output is: 


.nh 

off 

— no 

.hy 

on 

— no 

.he c 

none 

none no 


No hyphenation. Automatic hyphenation is turned off. Words con¬ 
taining hyphens (e.g., mother-in-law) may still be split across lines. 

Hyphenate. Automatic hyphenation is turned on. 

Hyphenation indicator character is set to “c” or removed. During 
text processing, the indicator is suppressed and will not appear in 
the output. Prepending the indicator to a word has the effect of 
preventing hyphenation of that word. 
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15. Summery 

The following are qualities of MM that have been emphasized in its design in approximate order of impor¬ 
tance: 

• Robustness in the face of error—A user need not be an nroff/troff expert to use MM macros. When 
the input is incorrect, either the macros attempt to make a reasonable interpretation of the error or 
an error message describing the error is produced. An effort has been made to minimize the possibility 
that a user would get cryptic system messages or strange output as a result of simple errors. 

• Ease of use for simple documents— It is not necessary to write complex sequences of commands to pro¬ 
duce documents. Reasonable macro argument default values are provided where possible. 

• Parameterization— There are many different preferences in the area of document styling. Many param¬ 
eters are provided so that users can adapt input text files to produce output documents to their respec¬ 
tive needs over a wide range of styles. 

• Extension by moderately expert users—A strong effort has been made to use mnemonic naming conven¬ 
tions and consistent techniques in construction of macros. Naming conventions are given so that a user 
can add new macros or redefine existing ones if necessary. 

• Device independence—A common use of MM is to produce documents on hard copy via teletypewriter 
terminals using the nroff formatter. Macros can be used conveniently with both 10- and 12-pitch termi¬ 
nals. In addition, output can be displayed on an appropriate CRT terminal. Macros have been con¬ 
structed to allow compatibility with the troff(l) formatter so that output can be produced on both a 
phototypesetter and a teletypewriter/CRT terminal. 

• Minimization of input— The design of macros attempts to minimize repetitive typing. For example, if 
a user wants to have a blank line after all first- or second-level headings, the user need only set a specific 
parameter once at the beginning of a document rather than type a blank line after each such heading. 

• Decoupling of input format from output style— There is but one way to prepare the input text although 
the user may obtain a number of output styles by setting a few global flags. For example, the .H macro 
is used for all numbered headings, yet the actual output style of these headings may be made to vary 
from document to document or within a single document 
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INPUT: 


.HD "May 31, 1979 " 

.TL 33W55 

Out-of-Hours Course Description 

.AU "D. W. Stevenson" DWS PY 9876 5«32 IX—123 

.MT 0 

.DS 

J. M. Jones: 

.DE 

.P 

Please use the following description for the out-of-hours course 
* I 

Document Preparation on the UNIX* 

.R 

.FS * 

Trademark of Bell Laboratories. 

.FE 

.1 "Time-Sharing Operating System:" 

.P 

The course is intended for clerks, typists, and others 

who intend to use the UNIX system for preparing documentation. 

The course will cover such topics as: 

.VL 18 

.LI Environment: 

utilizing a time-sharing computer system; 

accessing the system; using appropriate output terminals. 

.LI Files: 

how text is stored on the system; 
directories; manipulating files. 

.LI "Text editing:" 

how to enter text so that subsequent revisions are easier to make; 
how to use the editing system to add, delete, and move lines of text; 
how to make corrections. 

.LI "Text processing:" 
basic concepts; 

use of general purpose formatting packages. 

.LI "Other facilities:" 

additional capabilities useful to the typist such as the 

.1 "spell, diff," 

and 

.1 grep 

commands, and a desk-calculator package. 

.LE 

•SG Jrm 
.NS 0 

S. P. I ename 
H. 0. Del 
M. Hill 
.NE 


Fig. 4.1 — Examples of a Simple letter (Sheet 1 of 3) 
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nraff OUTPUT: 

Bell Laboratories 

subject: Out-of-Hours Course Description - date: May 31, 1979 

Case 33«H55 

from: D. W, Stevenson 
PY 9876 
IX—123 x5**32 

J, M. Jones: 

Please use the following description for the out-of-hours course 
Document Preparation on the UHIX * Time-Sharing Operating System : 

The course is intended for clerks, typists, and others who intend to use 
the UHIX system for preparing documentation. The course will cover such 


topics as: 


Environment: 

utilizing a time-sharing computer system; accessing 
the system; using appropriate output terminals. 

Files: 

how text is stored on the system; directories; 
manipulating files. 

Text editing: 

how to enter text so that subsequent revisions are 
easier to make; how to use the editing system to add, 
delete, amd move lines of text; how to make 
corrections. 

Text processing: 

basic concepts; use of general-purpose formatting 
packages. 

Other facilities: 

additional capabilities useful to the typist such as 
the spell. diff. and grep commands, and a desk- 
calculator package. 

PY-9876-DWS-jrm 

D. W. Stevenson 

Copy to 

S. P. Lename 

H. 0. Del 

M. Hill 



• Trademark of Bell Laboratories. 

Fig. 4.1 — Examples of a Simple Letter (Sheet 2 of 3) 
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Bell Laboratories 


subject: Out-of-Hours Course Description - Case 334455 


date: May 31, 1979 


from: D. W. Stevenson 
PY 9876 
1X-123 x5432 


J. M. Jones: 


Please use the following description for the Out-of-Hours course Document Preparation on the 
UNIX * Timesharing System: 

The course is intended for clerks, typists, and others who intend to use the UNIX system for 
preparing documentation. The course will cover such topics as: 

utilizing a time-sharing computer system; accessing the system; using 
appropriate output terminals. 

how text is stored on the system; directories; manipulating files. 

how to enter text so that subsequent revisions are easier to make; how to 
use the editing system to add, dfelete, and move lines of text; how to make 
corrections. 


Environment: 

Files: 

Text editing: 


Text processing: basic concepts; use of general-purpose formatting packages. 

Other facilities: additional capabilities useful to the typist such as the spell, diff. and grep 

commands, and a desk-calculator package. 


PY-9876-DWS-jrm D. W. Stevenson 

Copy to 
S. P. Lename 
H. O. Del 
M. Hill 


* Trademark of Bell Laboratories. 

fig* 4.1 — Examples of a Simple Letter (Sheet 3 of 3) 
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INPUT: 

.P 

.FD 10 

This example illustrates several footnote styles 
for both labeled and automatically numbered footnotes. 

With the footnote style set to the NROFF default,- 

process the first footnote\*F 

.FS 

This is the first footnote text example (.FD 10). 

This is the default style for NROFF. 

The right margin is not justified. 

Hyphenation is not permitted. 

Text is indented, and the automatically generated label is 
right justified in the text-indent space. 

.FE 

and follow it by a second footnote.••••• 

.FS ••••• 

This is the second footnote text example (.FD 10). 

This is also the default NROFF style but with a long 
footnote label (•*•••) provided by the user. 

.FE 
.FD 1 

Footnote style is changed by using the .FD macro to 
specify hyphenation, right margin justification, 
indentation, and left justification of the label. 

This produces the third footnote,\*F 
.FS 

This is the third footnote example (.FD 1). 

The right margin is justified, the footnote text is indented, 
and the label is left justified in the text-indent space. 

Although not necessarily illustrated by this example, 
hyphenation is permitted. 

.FE 

and then the fourth footnote.\(dg 
.FS 4 

This is the fourth footnote example (.FD 1). 

The style is the same as the third footnote. 

.FE 
.FD 6 

Footnote style is set again via the .FD macro for no hyphenation, 
no right margin justification, 

no indentation, and with the label left justified. 

This produces the fifth footnote.\*F 
.FS 

This is the fifth footnote example (.FD 6). 

The right margin is not justified, hyphenation is not permitted, 
footnote text is not indented, 

and the label is placed at the beginning of the first line. 

.FE 

Fig. 4.2 — Examples of Footnotes (Sheet 1 of 2) 
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- 2 - 


OUTPUT: 

This example illustrates several footnote styles for both 
labeled and automatically numbered footnotes. With the 
footnote style set to the NROFF default, process the first 
footnote 1 and follow it by a second footnote.••••• Footnote 
style is changed by using the .FD macro to specify 
hyphenation, right margin justification, indentation, and 
left justification of the label. This produces the third 
footnote, and then the fourth footnote.+ Footnote style is 
set again via the .FD macro for no hyphenation, no right 
margin justification, no indentation, and with the label 
left justified. This produces the fifth footnote. 


1. This is the first footnote text example (.FD 10 ). This 
is the default style for NROFF. The right margin is not 
justified. Hyphenation is not permitted. Text is 
indented, and the automatically generated label is right 
justified in the text-indent space. 

•••** This is the second footnote text example (.FD 10). 

This is also the default NROFF style but with a long 
footnote label (••*••) provided by the user. 

2. This is the third footnote example (.FD 1). The right 
margin is justified, the footnote text is indented, and 
the label is left justified in the text-indent space. 
Although not necessarily illustrated by this example, 
hyphenation is permitted. 

▼ This is the fourth footnote example (.FD 1). The style 
is the same as the third footnote. 

3. This is the fifth footnote example (.FD 6). The right 
margin is not justified, hyphenation is not permitted, 
footnote text is not Indented, and the label is placed at 
the beginning of the first line. 

Fig. 4.2 — Examples of Footnotes (Sheet 2 of 2) 
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TABLE 4.A 


MM MACRO NAMES SUMMARY 


MACRO 

DESCRIPTION {PARAGRAPH} 

1C 

1-column processing {12.4} 

.1C 

2C 

2-column processing {12.4} 

.2C 

AE 

Abstract end {6.5} 

.AE 

AF 

Alternate format of “Subject/Date/From” block {6.9} 

.AF (company-name] 

AL 

Automatically incremented list start {5.11.1} 

.AL [type] [text-indent] [1] 

AS 

Abstract start {6.5} 

.AS [arg] [indent] 

AT 

Author’s title {6.3} 

.AT [title] ... 

AU 

Author information {6.3} 

.AU name [initials] [loc] [dept] [ext] [room] [arg] [arg] [arg] 

AV 

Approval signature {6.11.3} 

.AV [name] 

B 

Bold {121} 

.B [bold-arg] [previous-font-arg] [bold] [prev] [bold] [prev] 

BE 

Bottom block end {9.7} 

.BE 

BI 

Bold/Italic {12.1} 

.BI [bold-arg] [italic-arg] [bold] [italic] [bold] [italic] 

BL 

Bullet list start {5.11.2} 

.BL [test-indent] [1] 

BR 

Bold/Roman {12.1} 

.BR [bold-arg] [Roman-arg] [bold] [Roman] [bold] [Roman] 

BS 

Bottom block start {9.7} 

.BS 

CS 

Cover sheet {10.2} 

.CS [pages] [other] [total] [figs] [tbls] [refs] 

DE . 

Display end {7.1} 

.DE 

DF 

Display floating start {7.2} 

.DF [format] [fill] [right-indent] 

DL 

Dash list start {51.1.3} 

.DL [text-indent] [1] 
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TABLE 4.A (Contd) 


MM MACRO NAMES SUMMARY 


MACRO 

DESCRIPTION PARAGRAPH 

DS 

Display static start {7.1} 

.DS [format] [fill] [right-indent] 

EC 

Equation caption [7.5] 

.EC [title] [override] [flag] 

EF 

Even-page footer {9.2.5} 

.EF [arg] 

EH 

Even-page header {9.2.2} 

.EH [arg] 

EN 

End equation display {7.4} 

.EN 

EQ 

Equation display start {7.4} 

.EQ [label] 

EX 

Exhibit caption (7.51 
.EX [title] [override] [flag] 

FC 

Formal closing (6.11) 

.FC [closing] 

FD 

Footnote default format {8.3} 

■FD [arg] [1] 

FE 

Footnote end {8.2} 

.FE 

FG 

Figure title {7.5} 

.FG [title] [override] [flag] 

FS 

Footnote start {8.2} 

•FS [label] 

H 

Heading—numbered {4.2} 

.H level [heading-text] [heading-suffix] 

HC 

Hyphenation character (3.4} 

.HC [hyphenation-indicator] 

HM 

Heading mark style {4.2.2.5} 

(Arabic or Roman numerals, or letters) 

.HM [argl] ... [arg7] 

HU 

Heading—unnumbered {4.3} 

.HU heading-text 

HX* 

Heading user exit X (before printing heading) {4.6} 

.HX dlevel rlevel heading-text 


’See note at end of table. 
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TABLE 4.A (Contd) 


MM MACRO NAMES SUMMARY 


MACRO 

DESCRIPTION PARAGRAPH 

HY* 

Heading user exit Y (before printing heading) {4.6} 

.HY dlevel rlevel heading-text 

HZ* 

Heading user exit Z (after printing heading) {4.6} 

.HZ dlevel rlevel heading-text 

1 

Italic (underline in the nroff formatter) {l2.l} 

.1 [italic-arg] [previous-font-arg] [italic] [prev] [italic] [prev] 

IB 

Italic/Bold {12.1} , r . tJ , 

.IB [italic-arg] [bold-arg] [italic] [bold] [italic] [bold] 

IR 

Italic/Roman {l2.l} . 

.IR [italic-arg] [Roman-arg] [italic] [Roman] [italic] [Roman] 

LB 

- List begin {5.2} 

.LB text-indent mark-indent pad type [mark] [Ll-space] [LB- 
space] 

LC 

List-status clear {5.3} 

.LC [list-level] 

LE 

List end {5.1.3} 

•LE [1] 

LI 

List item {5.1.2} 

.LI [mark] [1] 

ML 

Marked list start 15.1.1.4* 1 

.ML mark [text-indent] [1] 

MT 

Memorandum type {6.7} 

.MT [type] [addressee] or .MT [4] [1] 

ND 

New date {6.8} 

.ND new-date 

NE 

Notation end {6.11.2} 

.NE 

NS 

Notation start {6.11.2} 

.NS [arg] 

nP 

Double-line indented paragraphs {4.1} 

.nP 

OF 

Odd-page footer {9.2.6} 

.OF [arg] 

OH 

Odd-page header {9.2.3} 1 

.OH [arg] 

OK 

Other keywords for the Technical Memorandum cover sheet {6.6} 

.OK [keyword] ... 


’See note at end of table. 
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TABLE 4.A (Contd) 


MM MACRO NAMES SUMMARY 


MACRO 

DESCRIPTION PARAGRAPH 

OP 

Odd page jl2.8} 

.OP 

p 

Paragraph {4.1} 

.P [type] 

PF 

Page footer • {9.2.4} 

.PF [arg] 

PH 

Page header (9.2.1} 

•PH [arg] 

PM 

Proprietary marking {9.9} 

.PM [code] 

PX* 

Page-header user exit {9.6} 

.PX 

R 

Return to regular (Roman) font {12.1} 

.R 

RB 

Roman/bold {l2.l} 

.RB [Roman-arg] [bold-arg] [Roman] [bold] [Roman] [bold] 

RD 

Read insertion from terminal jl2.ll} 

.RD [prompt] [diversion] [string] 

RF 

Reference end {11.2} 

.RF 

RI 

Roman/Italic (l2.l) 

.RI [Roman-arg] [italic-arg] [Roman] [italic] [Roman] [italic] 

RL 

Reference list start {5.1.1.5} 

.RL [text-indent] [1] 

RP 

Produce reference page {11.4} 

.RP [arg] [arg] 

RS 

Reference start {11.2} 

.RS [string-name] 

S 

Set troff formatter point size and vertical spacing {12.9} 

.S [size] [spacing] 

SA 

Set adjustment (right-margin justification) default {12.2} 

.SA [arg] 

SG 

Signature line {6.11.1} 

.SG [arg] [1] 

SK 

Skip pages {12.7} 

.SK [pages] 


’See note at end of table. 
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TABLE 4.A (Contd) 


MM MACRO NAMES SUMMARY 


MACKO 

DESCRIPTION PARAGRAPH 

SM 

Make a string smaller {12.9} 

•SM stringl [string2] [string3] 

SP 

Space vertically {12.6} 

.SP [lines] 

TB 

Table title {7.5} 

.TB [title] [override] [flag] 

TC 

Table of contents {lO.l} 

.TC [slevel] [spacing] [tlevel] [tab] [headl] [head2] [head3] 
[head4] [head5] 

TE 

Table end {7.3} 

.TE 

TH 

Table header {7.3} 

.TH [N] 

TL 

Title of memorandum {6.2} 

.TL [charging-case] [filing-case] 

TM 

Technical Memorandum number(s) {6.4} 

.TM [number] ... 

TP* 

Top-of-page macro {9.6} 

.TP 

TS 

Table start {7.3} 

.TS [H] 

TX* 

Table of contents user exit {10.1} 

.TX 

TY* 

Table of contents user exit {lO.l} 

(suppresses “CONTENTS”) 

.TY 

VL 

Variable-item list start {5.1.1.6} 

.VL text-indent [mark-indent] [1] 

VM 

Vertical margins {9.8} 

.VM [top] [bottom] 

WC 

L 

Footnote and Display Width control {12.4} 

.WC [format] 


“Macros marked with an asterisk are not, in general, called (invoked) 
directly by the user. They are “user exits” defined by the user and called 
by the MM macros from inside header, footer, or other macros. 
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TABLE 4.B 


STRING NAMES SUMMARY 


STRING 

NAM! 

DESCRIPTION {PARAGRAPH} 

BU 

Bullet {3.7} 

NROFF: ♦ 

TROFF: • 

Ci 

Table of contents indent list {lO.l} 

Up to seven ergs (must be scaled) for heading levels 

DT 

Date {6.8} 

Current date, unless overridded 

Month, day, year (e.g., July 16, 1982) 

EM 

Em dash string {3.81 

Produces an em dash in the iroff formatter and a double hyphen 
in nroff 

F 

Footnote numberer {8.1}- 
NROFF:\u\\n+(:p\d 

TROFF:\v‘-.4m’\s-3Wn+(:p\sO\v‘.4m’ 

HF 

Heading font list {4.2.2.4.1} 

Up to seven codes for heading levels 1 through 7 

3 3 2 2 2 2 2 (levels land 2 bold, 3 through 7 underlined in the 
nroff formatter and italic in troff) 

HP 

Heading point size list {4.2.2.4.3} 

Up to seven codes for heading levels 1 through 7 

Le 

Title for LIST OF EQUATIONS {7.6} 

Lf 

Title for LIST OF FIGURES {7.6} 

Lt 

Title for LIST OF TABLES {7.6} 

Lx 

Title for LIST OF EXHIBITS {7.6} 

RE 

SCCS Release and Level of MM {12.3} 

Release.Level (e.g., 10.129) 

Rf 

Reference numberer {11.1} 

Rp 

Title for references {il.4} 

Tm 

Trademark string {3.9} . 

Places the letters “TM” one-half line above the text that it follows 
Seven accent strings are also available {12.10}. 


Note 1: If the released-paper style is used, then, in addition to the above 
strings, certain BTL location codes are defined as strings: these loca¬ 
tion strings are needed only until the .MT macro is called {6.7} . 
Currently, the following are recognized: 

AK, AL, ALF, CB, CH, CP, DR, FJ, HL, HO, HOH, HP, IH, IN. 
INH, IW, MH, MV, PY, RD, RR, WB, WH, and VVV. 

Note 2: Paragraph 1.5 has notes on setting and referencing strings. 
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TABLE 4.C 


NUMBER REGISTER NAMES SUMMARY 


REGISTER 

DESCRIPTION {PARAGRAPH} 

A*t 

Handles preprinted forms and Bell System logo {2.4) 

0, [0:2] 

Au 

Inhibits printing author’s location, department, room, and 
extension in "from” portion of a memorandum {6.3) 

1. [0:1] 

c*t 

Copy type {2.4} 

Original, Draft, etc. 

0 (Original), [0:4] 

Cl 

Contents level [4.4] 

Level of headings saved for table of contents 

2, [0:7] 

CP 

Placement of list of figures, etc. [10.1] 

1 (on separate pages), [0:1] 

D*t 

Debug flag {2.4} 

0, [0:1] 

De 

Display eject register for floating displays {7.2} 

0, [0:1] 

Df 

Display format register for floating displays {7.2} 

5, [0:5] 

Ds 

Static display pre- and post-space {7.1} 

1. [0:1] 

E*t 

Controls font of the Subject/Date/From fields {2.4} 

1 (nroff) 0 (troff), [0:1] 

Ec 

Equation counter, used by .EC macro {7.5} 

0, [0:?], incremented by one for each .EC call. 

Ej 

Page-ejection flag for headings {4.2.2.1} 

0 (no eject), [0:7] 

Eq 

Equation label placement {7.4} 

0 (right-adjusted), [0:1] 

Ex 

Exhibit counter, used by .EX macro {7.5} 

0, [0:?], incremented by one for each .EX call. 

Fg 

Figure counter, used by .FG macro {7.5} 

0, [0:?], incremented by one for each .FG call. 

Fs 

Footnote space (i.e., spacing between footnotes) {8.4} 

1. [0:?] 

HI 

through 

H7 

Heading counters for levels 1 through 7 {4.2.2.S} 

0, [0:?], incremented by .H of corresponding level or .HU if at 
level given by register Hu. H2 through H7 are reset to 0 by any 
heading at a lower-numbered level. 


*tSee notes at end of table. 
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NUMBER REGISTER NAMES SUMMARY 


MGiSTKX 

DESCRIPTION [PARAGRAPH] 

Hb 

Heading break level (after .H and .HU) {4.2.2.2J2, (0:7) 

He 

Heading centering level for .H and .HU {4.2.2.3J 

0 (no centered headings), [0:7] 

Hi 

Heading temporary indent (after .H and .HU) {4.2.2.2J 

1 (indent as paragraph), [0:2] 

Hs 

Heading space level (after .H and .HU) |4.2.2.2.} 

2 (space only after .H 1 and ,H 2), [0:7] 

Ht 

Heading type {4.2.2.5} 

For .H: single or concatenated numbers 

0 (concatenated numbers: 1.1.1, etc.), [0:1] 

Hu 

Heading level for unnumbered heading (.HU) {4.3} 

2 (.HU at the same level as .H 2. [0:7] 

Hy 

Hyphenation control for body of document {3.4} 

0 (automatic,hyphenation off), [0:1] 

L*t 

Length of page {2.4} 

66, [20:?] (lli, [2i:?] in troff formatter) 

For nroff formatter, these values are unsealed numbers 
representing lines or character positons; for troff formatter, 
these values must be scaled.. 

Le 

List of equations {7.6} 

0 (list not produced) [0:1] 

Lf 

List of figures {7.6} 

1 (list produced) [0:1] 

Li 

List indent {5.1.1.1} 

6 (nroff) 5 (troff), [0:?] 

Ls 

List spacing between items by level {5.1.1.1} 

6 (spacing between all levels) [0:6] 

Lt 

List of tables {7.6} 

1 (list produced) [0:1] 

Lx 

List of exhibits {7.6} 

1 (list produced) [0:1] 

N*t 

Numbering style (2.4} 

0, [0:5] 

Np 

Numbering style for paragraphs {4.1} 

0 (unnumbered) [0:1] 


*tSee notes at end of table. 
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TABLE 4.C (Contd) 


NUMBER REGISTER NAMES SUMMARY 


REGISTER 

DESCRIPTION {PARAGRAPH} 

o*t 

Offset of page {2.4} 

.75i, [0:?] (0.5i, [0i:?] in troff formatter) 

For nroff formatter, these values are unsealed numbers 
representing lines or character positions; for troff formatter, 
these values must be scaled. 

Oc 

Table of contents page numbering style {10.1} 

0 (lowercase Roman), [0:1] 

Of 

Figure caption style {7.5} 

0 (period separator), [0:1] 

p+ 

Page number manager by MM {2.4} 

0, [0:?] 

Pi 

Paragraph indent {4.1} 

5 (nroff) 3 (troff), [0:?] 

Ps 

Paragraph spacing {4.1} 

1 (one blank space between paragraphs), [0:?] 

Pt 

Paragraph type {4.1} 

0 (paragraphs always left justified), [0:2] 

Pv 

“PRIVATE” header {9.10} 

0 (not printed), [0:2] 

Rf 

Reference counter, used by .RS macro {ll.l} 

0, [0:?], incremented by one for each .RS call. 

S*t 

The troff formatter default point size {2.4} 

10, [6:36] 

Si 

Standard indent for displays {7.1} 

5 (nroff) 3 (troff), [0:?] 

T*t 

Type of nroff output device {2.4} 

0, [0:2] 

Tb 

Table counter, used by .TB macro {7.5} 

0, [0:?], incremented by one for each .TB call. 

U*t 

Underlining style (nroff) for .H and .HU {2.4} 

0 (continuous underline when possible), [0:1] 

w*t 

Width of page (line and title length) {2.4} 

6i, [10:1365] (6i, [2i:7.54i] in the troff formatter) 


*An asterisk attached to a register name indicates that this register can be set 
only from the comman line or before the MM macro definitions are read by the 
formatter {2.4, 2.5} . 

tParagraph 1.5 has notes on setting and referencing registers. Any register 
having a single-character name can be set from the command line. 
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TABLE 4.D 


ERROR MESSAGES 


BtROR MESSAGE 

DESCRIPTION 

MM Error Mouogos 


An MM error message has a standard part followed by a variable part. The standard part has the form: 

ERROR:(/j7euaine)input line 

a 

Variable parts consist of a descriptive message usually beginning with a macro name. They are listed 
below in alphabetical order by macro name, each with a more complete explanation. 

Check TL. AU, AS, AE, MT 
sequence 

The correct order of macros at the start of a memorandum is 
shown irr {6.1} . Something has disturbed this order. 

Check TL, AU, AS, AE, NS, NE, 

MT sequence 

The correct order of macros at the start of a memorandum is 
shown in {6.1} . Something has disturbed.this order. Occurs if the 
.AS 2 {6.5}macro was used. 

CS:cover sheet too long 

Text of the cover sheet is too long to fit on one page. The abstract 
should be reduced or the indent of the abstract should be decreased 
{6.5} . 

DE:no DS or DF active 

A .DE macro has been encountered, but there has not been a previ¬ 
ous .DS or .DF macro to match it. 

DF:illegal inside TL or AS 

Displays are not allowed in the title or abstract. 

DF:missing DE 

A .DF macro occurs within a display, i.e., a .DE macro has been 
omitted or mistyped. 

DF:missing FE 

A display starts inside a footnote. The likely cause is the omission 
(or misspelling) of a .FE macro to end a previous footnote. 

DF:too many displays 

More than 26 floating displays are active at once, i.e., have been 
accumulated but not yet output. 

DSiillegai inside TL or AS 

Displays are not allowed in the title or abstract. 

DSimissing DE 

A .DS macro occurs within a display, i.e., a .DE has been omitted or 
mistyped. 

DS:missing FE 

A display starts inside a footnote. The likely cause is the omission 
(or misspelling) of a .FE to end a previous footnote. 

FE:no FS active 

A .FE macro has been encountered with no previous .FS to match 
it. 

FS:missing DE 

A footnote starts inside a display, i.e., a .DS or .DF occurs without 
a matching .DE. 

FS:missing FE 

A previous .FS macro was not matched by a closing FE, i.e., an 
attempt is being made to begin a footnote inside another one. 

H:bad arg: value 

The first argument to the .H macro must be a single digit from one 
to seven, but value has been supplied instead. 

H:missing arg 

The H macro needs at least one argument. 

H:missing DE 

A heading macro (.H or .HU) occurs inside a display. 
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TABLE 4.D (Contd) 

ERROR MESSAGES 

ERROR MESSAGE 

DESCRIPTION 

H:missing FE 

HU:missing arg 

LB:missing arg(s) 

LB:too many nested lists 

LE:mismatched 

A heading macro (.H or .HU) occurs inside a footnote. 

The .HU macro needs one argument. 

The .LB macro requires at least four arguments. 

Another list was started w'hen there were already six active lists. 

The .LE macro has occurred without a previous .LB or other list- 
initialization macro {5.1.1} . Although this is not a fatal error, 
the message is issued because there almost certainly exists some 
problem in the preceding text. 

LI:no lists active 

The .LI macro occurred without a preceding list-initialization 
macro. The latter has probably been omitted or has been separated 
from the .LI by an intervening .H or .HU. 

MUmissing arg 

ND:missing arg 

RF:no RS active 

The .ML macro requires at least one argument. 

The .ND macro requires one argument. 

The .RF macro has been encountered with no previous .RS to 
match it. 

RP:missing RF 

RS:missing RF 

S:bad arg:value 

A previous .RS macro was not matched by a closing .RF. 

A previous .RS macro was not matched by a closing .RF. 

The incorrect argument value has been given for the .S macro 
{12.9} . 

SA:bad arg:value 

The argument to the .SA macro (if any) must be either 0 or 1. the 
incorrect argument is shown as value. 

SG:missing DE 

SG:missing FE 

SG:no authors 

The .SG macro occurred inside a display. 

The .SG macro occurred inside a footnote. 

The .SG macro occurred without any previous .AU macro(s). 

VLrmissing arg 

WC:unknown option 

The .VL macro requires at least one argument. 

An incorrect argument has been given to the .WC macro {l2.4j . 

Formatter Error Messages 



Most messages issued by the formatter are self-explanatory. Those error messages over which the user 
has some control are listed below. Any other error messages should be reported to the local system 


support group. 


Cannot do ev 

Caused by: 

a. setting a page width that is negative or extremely short 

b. setting a page length that is negative or extremely short 

c. reprocessing a macro package (e.g., performing a .so request on 
a macro package that was already requested on the command 
line) 

d. requesting the troff formatter (an option on a document that is 
longer than ten pages). 
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TABLE 4.D (Contd) 

ERROR MESSAGES 

ERROR MESSAGE 

DESCRIPTION 

Cannot execute filename 

Cannot open filename 

Given by the .! request if the filename is not found. 

Indicates one of the files in the list of files to be processed cannot 
be opened. 

Exception word list full 

Indicates too many words have been specified in the hyphenation 
exception list (via .hw requests). 

Line overflow 

Indicates output line being generated was too long for the format¬ 
ter line buffer capacity. The excess was discarded. Likely causes 
for this message are very long lines or words generated through 
the misuse of \c of the .cu request or very long equations produced 
by eqn(l)/neqn. 

Nonexistent font type 

Nonexistent macro file 

Nonexistent terminal type 

Out of temp file space 

Indicates a request has been made to mount an unknown font. 

Indicates the requested macro package does not exist. 

Indicates the terminal options refer to an unknown terminal type. 

Indicates additional temporary space for macro definitions, diver¬ 
sions, etc. cannot be allocated. This message often occurs because 
of unclosed diversions (missing .FE or .DE), unclosed macro defini¬ 
tions (e.g., missing or a huge table of contents. 

Too many page numbers 

Indicates the list of pages specified to the -o formatter option 
is too long. 

Too many number registers 

Indicates the pool of number register names is full. Unneeded reg¬ 
isters can be deleted by using the .rr request. 

Too many string/macro names 

Indicates the pool of string and macro names is full. Unneeded 
strings and macros can be deleted using the .rm request. 

Word overflow 

Indicates a word being generated exceeds the formatter word 
buffer capacity. Excess characters were discarded. Likely causes 
for this message are very long lines, words generated through the 
misuse of \c of the .cu request, or very long equations produced by 
eqn(l)/neqn. 
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V. VIEWGRAPHS AND SUDES MACROS 

1. Introduction 

This section describes a package of UNIX operating system troff(l) 1 formatter macros called MV designed 
for typesetting viewgraphs and slides. It is assumed that the reader has a basic knowledge of the UNIX operat¬ 
ing system, the text editor ed(l), and the troff formatter. 

With the MV macros, viewgraphs can be prepared in a variety of dimensions, as well as 35mm slides and 
2x2 “super-slides”. These transparencies can be made in a variety of styles, in different fonts, with oversize ti¬ 
tles, and with highlighted subordination levels. Because text from which the foils are typeset is stored on the 
UNIX operating system, the contents of a foil can be readily changed to include new data or can be incorporated 
into a new presentation. Text of the foils can be passed through spell(l), or preprocessed by eqn(l), tbl(l), 
cw(l), etc. 

It is not possible to include artwork, graphics, or multicolored text in foils made with this macro package 
except by manual cut-and-paste methods. 

2. Examples 

Before explaining the macros in detail, the formatting process is illustrated with some examples. 

2.1 Trivial Example 

The following text file is given the file name of trivial: 

.Sw 

Six stages of a project 
.B 

wild enthusiasm 
.B 

disillusionment 

.B 

total confusion 
.B 

search for the guilty 
.B 

punishment of the innocent 
.B 

promotion of the non-participants 

The .Sw is a foil-start macro and is defined in paragraph 3.1. The following UNIX operating system command 
generates the viewgraph illustrated in Fig. 5.1: 

mvt trivial 

1 The notation name (N) indicates entry name in Section N of the User’s Guide—Unix Operating System. 
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2.2 Lets Trivial Example 

The foil that results from typesetting the following input is illustrated in Fig. 5.2.* 

.Vw 2" Less Trivial" " June 29,1980 " 

.T ” What the Walrus Said" 

“The time has come," the Walrus said, 

.BR 

‘To talk of many things: 

.1.5 
.B 

Of shoes\(emand ships\(emand sealing wax\(em 
.B 

Of cabbages\(emand kings\(em 
.B 

And why the sea is boiling hot\(em 
.B 

And whether pigs have wings.” 

The .Vw (paragraph 3.1) is another foil-start macro. Other macros (.T, .BR, and .1) in this example will be 
explained later. 

2.3 Other Examples 

Inputs that generate foils of Fig. 5.3 through 5.7 are shown below. These foils illustrate the effect of macros 
that are discussed in the following paragraphs. 

The input for Fig. 5.3 is: 

.Vh 3 " Levels & Marks " 

.T " Foil Levels & Level Marks " 

This is the .A (left margin) level; 

.B 

this is the .B level, 

.B 

as is this; 

.C 

this is the .C level, 

.C 

as is this; 

.D 

and this is the .D level, 

.D 

as is this. 

.A 

The large bullet, the dash, and the small 
bullet are the default “marks” for 
levels .B, .C, and .D, respectively. 

However, these three levels can also 
be marked arbitrarily: 

.BB. 

2 The input string \ (em is the troff formatter name for the “em dash” (long dash). 
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Like this (this is the .B level); 

.C 3. 

like this (this is the .C level); 

.D d. 

like this (this is the .D level), or 
.D iv. 

like this, or even 
\&.D \(rh*\(bu +4 
like this. 

.A 

The .A level cannot be marked. 

.B 

An arbitrary number of lines of text 
can be included in any item at any level; 
the text will be filled, but neither adjusted 
nor hyphenated, just like this .B level item. 

The input for Fig. 5.4 is: 

.DF1R 
.VS 4 Complex 

•T" Of Bits & Bytes & Words" 

.S -4 
.1 3 A x 
it I 

But let your communication be. Yea, yea; 
Nay, nay: for whatsoever is more than these 
cometh of evil.* 

.ft 

.1 +1 a nospace 
Matthew 5:37 
.BR 
.S 

.10.A 

Binary notation has been around for a 
.S +6 
long 
.S 

time. 

.B 

The above verse tells us to use: 

.C 1) 

binary notation, 
it I 
and 
it 

.C 2) 

redundancy 
.D \(rh 

(in communicating) 

.B 

Binary notation is 
.U not 

suited for human use, above verse to 
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the contrary notwithstanding. 


.SP 
.S -2 
.TS 


box; 


delete 
11 c I c I c . 

System® Bits/Byte©Bytes/W ord©Bits/W ord 

IBM 7090/94®6®6®36 
IBM 360/370©8O4(D32 
PDP 11/70©8(D2<516 
.TE 
.S 

.S -4 

.u. 

.BR 

* The use of this verse in this context 
is plagiarized from C. Shannon. 

.S 

The input for Fig. 5.5 is: 

.deCW 
J .5 a 
.NF 



.deCN 


.FI 

.10 a 

i>F 1 R 2 I 3 CW 
.VS 5 " CW & EQN" 

.EQ 

gsize 18 
.EN 

.S 100 5.5 
Input 
.CW 
.EQ 

sum from k=l to inf m sup k-1 

' = ' 1 over l-:m 

.EN 

.CN 

Output 
.1 2 a 
.EQ 

sum from k=l to inf m sup k-1 

' = ' 1 over 1-m 

.EN 

.1 0 a 

Input 

.CW 

The equation $ f(t) ' - * 2 pi 



Page 240 





6/82 


ISSUE 1 


DOCUMENT PROCESSING GUIOE 


int sin ( omega t) dt $ 
is used here in running text, 
rather than being displayed. 
.CN 

Output 
.1.5 a 


.EQ 

delim $$ 

.EN 

.AD 

The equation $ f(t) *-* 2 pi 
int sin ( omega t) dt $ 
is used here in running text, 
rather than being displayed. 
.EQ 


delim off 
gsize 10 
.EN 


The input for Fig. 5.6 is: 


.VS 6 " The Works: Input" 

Input 

.S -4 

.CW 

.TS 

center doublebox; 

Cip+4 I Cip+4 S S 

MLLL 

*ICICIC 

“ICICIC 

LilClClN. 

UsersOHardware 

©_©_©_ 

®UNIX\* (Tm©Model©Serial 
®System©\ * ©Number 


OS Dev.©A©VAX©54 
SGS DEV.OB®11/70®3275 
Low-End©C©l 1/230221 


And now ...©T{ 

NA 

Some filled text and an equation: 
T}®T{ 

$ zeta (s) * prod 

from K=1 to inf k sup —s $ 

.AD 

T}©1.2 

.TE 

.CN 

The input for Fig. 5.7 is: 

.VS 7 " The Works: Output" 
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.EQ 

deiim $$ 
gsize 14 
.EN 

Output 
.1 0 a 
.SP 
.TS 

center doublebox ; * 

Cip+4 I Cip+4 S S 
* IL L L 
MCICIC 
“ICICIC 
Li I C I CI N . 

UsersOHardware 

(DUNIX\*(Tm0Model<DSerial 
(DSystem®\ ' (DN umber 

OS Dev.©A<DVAX®54 
SGS Dev.(5B<Dll/70(D3275 
Low-End(DC(Dll/23(D221 

And now ,..©T{ 

.NA 

Some filled text and an equation: 

T}(DT{ 

$ zeta (s) = prod 

from k=l to inf k sup -s $ 

.AD 

T{®1.2 

.TE 

.EQ 

deiim off 
gsize 10 
.EN 

3. Macros 

The following is an explanation of the MV macros which are summarized in mv(7) of the User’s Guide— 
UNIX Operating System . 

3.1 Foil-Start Macros 

Each foil must start with a foil-start macro. There are nine foil-start macros for generating nine different- 
sized foils; the names (and the corresponding mounting-frame sizes) of these macros are shown in Table 5.A. 

The naming convention for these nine macros is that the first character of the name (V or S) distinguishes 
between viewgraphs and slides, while the second character indicates whether the foil is square (S), small wide 
(w), small high (hr), big wide (W), or big high (H). Slides are thinner than the corresponding viewgraphs; there¬ 
fore the ratio of the longer dimension to the shorter one is larger for slides than for viewgraphs. As a result, 
slide foils can be used for viewgraphs, but not vice versa. On the other hand, viewgraphs can accommodate a 
bit more text. 

Note: The .VW and .SW macros produce foils that are 7x5.4 inches because commonly available typeset¬ 
ter paper is less than 9 inches wide. These foils must be enlarged by a factor of 9/7 before they can be used 
as 9-inch wide by 7-inch high viewgraphs. 
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Each foil-start macro causes the previous foil (if any) to be terminated, foil separators to be produced, and 
certain heading information to be generated. The default heading information consists of three lines of right- 
justified data: 

• The current date in the form mo/dy/yr 

• BTL 

• FOIL a 

where n is the sequence number in the current “run”. As explained below, this heading information is replaced 
by the three arguments of the foil-start macro if those arguments are given. 

The actual projection area is marked by “cross hairs” (plus signs) that fit into the corners of the viewgraph 
mount. This is an aid in positioning the foil for mounting. 

All foils other than the square (.VS) foil alto have a set of horizontal and vertical “crop marks”. These indi¬ 
cate how much of the foil will be seen if it is made into a slide, rather than into a viewgraph. 

Default heading information can be changed by specifying three optional arguments to the foil-start macro. 
Square brackets ([ ]) indicate that the argument they enclose is optional. 

•XX [ n ] (id ] ( date ) 

where: 

• XX stands for one of the nine foil-start macros 

• n is the foil identifier (typically a nuniber) 

• id is other identifying information (typically the initials of the person creating the foil) 

• date is usually the date. 

The resulting heading information consists of three lines of right-justified text: 

• id 

• date 

• FOIL n. 

If date and id are omitted on a foil-start macro, then the corresponding values (if any) from the previous foil- 
start macro are used. 

3.2 Level Macros 

The MV macros provide four levels of indentation, called .A, .B, .C, and D. Each of these level macros causes 
the text that follows it to be placed at the corresponding level of indentation. 

The amount of vertical spacing done by each level macro can be changed with the .DV macro (paragraph 
3.7). Figure 5.3 is devoted to the level macros. 
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3.2.1 The .A ltvtl 

•A [ x ] 

The leftmost level (left margin) is obtained by the .A macro. The .A level is automatically invoked by each 
of the foil-start macros. Each .A macro spaces a half-line from the preceding text, unless the x argument is spec¬ 
ified (x can be any character or string of characters); x suppresses the spacing. 

The .A macro does not generate a mark of any sort; it is the “left-margin" macro. Repeated .A calls are ig¬ 
nored, but each successive call of any of the other three level macros generates the corresponding mark. 

The .A macro can also be invoked through the .1 macro (paragraph 3.4). 

3.2.2 The .B Level 

.B [ mark [ size ] ] 

The .B level items are marked by a bullet (in slightly reduced point size). The text that follows the .B macro 
is spaced one half-line from the preceding text. 

The .B level mark may be changed by specifying the desired character string' as the first argument Without 
the second argument (size), the point size of the mark is not reduced. Thus, the following will produce a num¬ 
bered list 


.VS 

This is a list of things: 

.B 1. 

This is thing number 1. 

.B 2. 

This is thing number 2. 

.B 3. 

This is the third and last thing on this foil. 

It is possible to change the point size of the mark with the second argument (size). If given, it specifies the 
desired point-size change. An unsigned or positive (+) argument is taken as an increment; a negative (-) argu¬ 
ment is a decrement. An argument greater than 99 causes the mark to be reduced in size just as if it were the 
default mark, namely, the bullet After the mark is printed, the previous point size is restored. All these point- 
size changes are completely invisible to the user. 

3.2.3 The .C Level 

.C [ mark [ size ) ] 

The .C level is like the .B level except that it is indented farther to the right and the default mark is a long 
dash (\(em) in a slightly reduced point size. 

3.2.4 The .D Level 

.D [ mark [ size ) ] 

The .D level is indented farther to the right than the .C level and does not space from the previous text. 
It causes the following text to start on a new line. In other words, it causes a break (paragraph 3.10). Otherwise, 
it behaves like the .B and .C levels. The .D level default mark is a bullet smaller than that used for the .B level. 

' All character-string arguments that contain spaces must be quoted (“...”). 
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3.3 Titles 

.T string 

The .T macro creates a centered title from its argument (string). The argument must be enclosed withir 
double quotes ( " ..." ) if it contains spaces. The size of the title is four points larger than prevailing point size 
Any indentation established by the .1 macro (paragraph 3.4) has no effect on titles; they are always centered 
within the foil horizontal dimension. 

Figures 5.2, 5.3, and 5.4 illustrate the .T macro. 

3.4 Global Indents 

.1 [ indent ] [ a [ x ] ] 

The entire text (except titles) of the foil may be shifted right or left by the .1 macro. The first argument 
Undent) is the amount of indentation that is to be used to establish a new left margin. This argument may be 
signed positive or negative, indicating right or left movement from the current margin. If unsigned, the argu¬ 
ment specifies the new margin, relative to the initial default margin. If the argument is not dimensioned, it is 
assumed to be in inches (see (3,8) for legal troff formatter units). If the argument is null or omitted, Oi is as¬ 
sumed causing the margin to revert to the initial default margin. 

If a second argument is specified, the .1 macro calls the .A macro (paragraph 3.2.1) before exiting. The third 
argument, if present, is passed to the .A macro. 

Figures 5.2, 5.4, 5.5, and 5.7 illustrate the .1 macro. 

3.5 Point Sizes and Line Lengths 

-S [ ps ] (11) 

Each foil-start macro begins the foil with an appropriate default point size* and line length. Prevailing point 
size and line length may be changed by invoking the .S macro. If the ps argument is null, the previous point 
size is restored. If ps is signed negative, the point size is decremented by the specified amount. If ps is signed 
positive, it is used as an increment; and if ps is unsigned, it is used as the new point size. If ps is greater than 
99, the initial default point size is restored (Table 5.B). Vertical spacing is always 1.25 times the current point 
size. 

The second argument (II), if given, specifies line length. It may be dimensioned. If it is not dimensioned 
and less than 10, it is taken as inches. If it is not dimensioned and greater than or equal to 10, it is taken as 
troff formatter units (l/432nds of an inch) (paragraph 7.3). 

Figures 5.4, 5.5, and 5.6 illustrate the .S macro. 

3.6 Default Fonts 

.DF n font ( n font... ] 

The MV macros assume that the Helvetica Regular (also known as Geneva) font, mounted in position 1, is 
the default font. Additional fonts can be mounted and the default font can be changed. The .DF macro informs 
the troff formatter that font is in position n. The first-named font is the default font. Up to four pairs of argu¬ 
ments may be specified. 

* Default point sizes for each type of foil and corresponding maximum number of lines are given in Table 5.B. 
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The .DF macro must immediately precede a foil-start macro; the initial setting is equivalent to 
.DF 1 H 2 I 3 B 4 S 

Figures 5.4 and 5.5 illustrate the .DF macro. 


3.7 Default Vertical Space 

•DV { a ]( b 1 [ c ] [ d ] 

The default vertical space macro (.DV) allows changing the vertical spacing done by each of the four level 
macros (paragraph 3.2). The first argument (a) is the spacing for the .A macro, b is for the .B macro, c is for 
the .C macro, and d is for the .D macro. All non-null arguments must be dimensioned. Null arguments leave 
the corresponding spacing unaffected. The initial setting is equivalent to 

.DV .5v .5v .5v Ov 

3.8 Underlining 

ft 

.U stringl [ string2 ] 

The underline macro (.U) takes one or two arguments. The first argument ( stringl ) is the string of charac¬ 
ters to be underlined. The second argument (stringZ), if present, is not underlined but concatenated to the first 
argument. For example: 

.U phototypesetter 

produces 

photo typesetter 

while 


.U under line 


produces 

under line 

Figure 5.4 illustrates the .U macro. 

3.9 Synonyms 

The MV macro package recognizes the .AD, .BR, .CE, .FI, .HY, .NA, .NF, .NH, .NX, .SO, .SP, .TA, and .TI 
uppercase text synonyms for the corresponding lowercase troff formatter requests. The NROFF and TROFF 
User’s Manual found in part 3 of this document contains definitions of these requests. 

3.10 Brooks 

The .S, .DF, .DV, and .U macros do not cause a break. The .1 macro causes a break only if it is invoked with 
more than one argument. All other MV macros always cause a break. The troff formatter synonyms (paragraph 
3.9) .AD, .BR, .CE, .FI, .NA, .NF, .SP, and .TI also cause a break. 
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3.11 Text Pilling, Adjusting, and Hyphenation 

By default, the MV macros fill, but neither adjust nor hyphenate text. This is an aesthetic judgement that 
seems correct for foils. These defaults can, of course, be changed by using the .AD, .FI, .HY, .NA, .NF, and .NH 
macros (paragraph 3.9). 

4. Th# troff Preprocessors 

It is possible to use the various troff formatter preprocessors to typeset foils that require more powerful 
formatting capabilities. 

4.1 Tables 

The tbl(l) program can be used to set up columns of data within a viewgraph or slide. The .TS and .TE 
macros are not defined in the MV macro package, but are merely flags to tbl(l). The Table Formatting Program 
found in part 3 of this document describes the macros used for generating tables. Figures 5.4 and 5.7 illustrate 
the tbl program use. 

4.2 Mathematical Expressions 

The eqn(l) program can be used to typeset mathematical expressions and formulas on foils provided care 
is taken to specify proper fonts and point sizes. The Mathematics Typesetting Program found in part 3 of this 
document describes the macros used for processing equations. The .EQ and .EN macros are not defined in the 
MV macro package. Figures 5.5 and 5.7 illustrate the eqn program. 

4.3 Constant-Width Program Examples 

The constant-width font simulates computer-terminal and line-printer output and can be sometimes effec¬ 
tive in presenting computer-related topics. The cw(l) program, as well as Figures 5.5 and 5.6 illustrate the 
preprocessor. 

5. The Finished Product 
5.1 Phototype sett or Output 

mvt [ options ] file ... 

Typeset output is obtained via the mvt command where the argument /j7e contains text and macro invoca¬ 
tions for the foils, and options can be one or more of the following; 

* a preview output on a-terminal (other than a Tektronix 4014—paragraph 5.2) 

-e invoke eqn(l) 

-t invoke tbl(l) 

-T term direct output to term, where term can be one of the following; 

st STARE 
4014 Tektronix 4014 

vp Versatec printer 

Using a hyphen (-) in place of file causes the mvt command to read the standard input (rather than a file), 
as in the following example using the cw(l) preprocessor (paragraph 4.3). 
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cw [ options ] file ... I mvt [ options ) - 

5.2 Output Approximation on a Tormina! 

mvt -a file.name ... 

An approximation of the typeset output can be obtained by entering the mvt command. The resulting out¬ 
put shows the formatted foils except that 

o Point-si 2 e changes are not visible 

o Font changes cannot be seen 

o Titles that are too long appear proper 

o All horizontal motions are reduced to one horizontal space to the right 

• All vertical motions are reduced to one vertical space down. 

For example, it appears that lines of text following a .B, .C, or .D macro do not align properly (even though, 
in fact they do). 

Although alignment cannot be determined from this approximation, line breaks and the amount of vertical 
space used by the text can be observed. If the foil is not full, the macro package prints the number of blank lines 
(in the then current point size) that remain on the foil; if the foil is full, a warning is printed. If the text did 
overflow the foil, text will be printed after the “cross hairs.” 

5.3 Making Actual Viewgraphi and Slides 

Output of the typesetter is so-called “mechanical paper,” which is white, opaque photographic paper with 
black letters. There are several very simple processes (e.g., Thermofax, Bruning) for making transparent foils 
from opaque paper. Because some of these processes involve heat and because mechanical paper is heat sensitive, 
one should first make copies of the typesetter output on a good quality office copier and then use these copies 
for making transparencies. 

Getting slides made is a much more complicated photographic process that is best left to professionals. It 
is possible to make both positive (opaque letters on transparent background) and negative (transparent letters 
on opaque background) slides, as well as colored-background slides, etc. 

6. Suggestions For Use 

The following suggestions have been derived from experience, from the examination of several other macro 
packages for making foils, and from some publications that discuss good and bad foil-making practices: 

e The most useful foil sizes are .VS and .Vw (or .Sw). This is because most projection screens are either 
square or wide (wider than they are tall) and also because the resulting foils are smaller, easier to carry, 
and require no enlargement before use. 

• Reducing point size below the default value should be avoided. Default point size for each type of foil 
(Table 5.B) is the smallest point size that will result in a foil that is legible by an audience of more than 
a dozen people. If there is more text than fits onto a foil, two or more foils should be used instead of 
reducing the point size. 

• Numerous font changes should be avoided. A foil with more than two typefaces looks cluttered and dis¬ 
tracts the viewer. 
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• Underlined typeset text should be avoided. Even though this package contains a macro for underlining, 
it should not be used. Underlined typeset text almost always looks bad; instead use a different typeface. 

• The Helvetica sans-serif font is thicker and easier to read than the Times Roman serif font normally 
used for typesetting. On the other hand, the Times Roman font permits more text to be squeezed onto 
a foil. If it is intended to use italic and/or bold typefaces, either the Helvetica regular, italic, and 
medium* 

.DF 1 H 2 HI 3 HM 

or the Times Roman regular, italic, and bold 
.DF 1 R 2 I 3 B 

should be mounted via the .DF macro (paragraph 3.6). Bold typefaces tend to be a bit overwhelming. 
Choice of fonts is primarily a matter of personal aesthetics. The following table identifies fonts used 
in the examples of Fig. 5.1 through 5.7. 

1, 2, and 3 H (default) 

4, 7 R and I 

5,6 R and CW 

• The .SP macro can be used to insert a bit of additional white space (for instance, .5v or lv, where v means 
“vertical space”) at the top of each foil (i.e., increase the top margin). 

• Normal uppercase and lowercase text is more legible than uppercase text only.* Uppercase and lower¬ 
case alphabets have evolved and been used for many years because they result in more legible text. Fur¬ 
thermore, such text is less bulky than uppercase text only, so more information can be put onto a foil 
without crowding. 

• Foils for a presentation should be made as consistent as possible. Changing fonts, typefaces, point sizes, 
etc., from foil to foil tends to distract the viewer. While it is possible to introduce emphasis and draw 
the viewer’s attention to particular items with such changes, this works only if it is done purposefully 
and sparingly. Overuse of these techniques is almost always counter-productive. 


In summary, the dictum that “the medium is the message” does not apply to foil making. When in doubt: 

• Do not change point sizes. 

• Do not change fonts or typefaces. 

• Do not underline. 

• Use many “sparse” foils rather than a few “dense” ones. 

• Use fewer words rather than more. 

• Use larger point sizes rather than smaller. 


5 Helvetica Medium is really a bold typeface. 

* The only exception to this rule are foils set in a point size so small that lowercase characters simply cannot 
be read. This is usually the case for foils produced on a normal typewriter. 
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• Use larger top and bottom margins rather than smaller. 

• Use normal uppercase and lowercase text rather than uppercase text only. 

7. Warnings 

7.1 Us* of troff Form a ft or Requests 

In general, it is not advisable to intermix arbitrary troff formatter requests with the MV macros because 
this often leads to undesirable (and sometimes astonishing) results. The “safe" requests are ones for which up¬ 
percase text synonyms have been defined in the MV package (paragraph 3.9). Other troff formatter requests 
should be used sparingly (if at all) and with care and discipline. Particularly dangerous are requests that affect 
point size, indentation, page offset, line and title lengths, and vertical spacing between lines. The .S and .1 
macros should be used instead (paragraphs 3.5 and 3.4). 

7.2 Reserved Names 

Certain names are used internally by this macro package. In particular, all 2-character names starting with 
either ) or ) are reserved. Names that are the same as names of the MV macros and strings described in this 
part or names that are the same as troff names cannot be used. Furthermore, if any of the preprocessors (Part 
4) are used, their reserved names must also be avoided. 

7.3 Miscellaneous 

The .S macro changes the point size and vertical spacing immediately, but a line-length change requested 
with that macro does not take effect until the next-level macro call. 

Specifying a third argument to the .S macro usually results in a disaster. 

The string Tm (invoked as \*(Tm) generates a trademark symbol. 

The tilde (%) is defined by the MV macros as a “nonpaddable” space; that is, the tilde may be used wherever 
a fixed-size (nonadjustable) space is desired. To override this definition, the following line should be included 
in the input file: 

.tr 

8. Dimensional Details 

For each style of viewgraph Table 5.B shows the default point size; the maximum number of lines of text 
(at the default point size); and the height, width, and aspect ratio, both nominal and actual. 
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Six stages of a project: 

• wild enthusiasm 

• disillusionment 

• total confusion 

• search for the guilty 

• punishment of the innocent 

• promotion of the non-participants 


5/21/82 
BTL 
FOIL 1 


+ 



+ 


+ 


Fig. 5.1 — Trivial Example 
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June 29. 1980 
Laas Trivial 
FOIL 2 


+ + 

What the Walrus Said 

“The time has come,” the Walrus said, 

“To talk of many things: 

• Of shoes—and ships—and sealing wax— 

• Of cabbages—and kings— 

• And why the sea is boiling hot— 

• And whether pigs have wings.” 


+ 


+ 


Fig. 5.2 — less Trivial Example 







ISSUE 1 


DOCUMENT PROCESSING GUIDE 


June 29. 1980 
Levels & Marks 
FOIL 3 


Foil Levels & Level Marks 

This is the .A (left margin) level; 

• this is the .B level, 

• as is this; 

— this is the .C level, 

— as is this; 

• and this is the .D level, 

• as is this. 

The large bullet, the dash, and the small 
bullet are the default “marks” for levels .B, 
.C, and .D, respectively. However, these 
three levels can also be marked arbitrarily: 

B. Like this (this is the .B level); 

3. like this (this is the .C level); 
d. like this (this is the .D level), or 
iv. like this, or even 
• like this. 

The .A level cannot be marked. 

• An arbitrary number of lines of text can 
be included in any item at any level; 
the text will be filled, but neither 
adjusted nor hyphenated, just like this 
.B level item. 


i 


Fig. 5.3 — Example of Foil Levels 
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June 29. 1980 
Complex 
FOIL 4 



Of Bits & Bytes & Words 


But let your communication be, 

Yea, yea; Nay, nay: for whatsoever 
is more than these cometh of evil* 
Matthew 5:37 

Binary notation has been around for a long time. 

• The above verse tells us to use: 

1) binary notation, and 

2) redundancy 

(in communicating) 

• Binary notation is not suited for human use, 
above verse to the contrary notwithstanding. 


System 

Bits/Byte 

Bytes/Word 

Bits/Word 

IBM 7090/94 

6 

6 

36 

IBM 360/370 

8 

4 

32 

PDP 11/70 

8 

2 

16 


* The use of this verse in this context is plagiarized from C. Shannon. 




+ 


Fig. 5.4 — Example of Square Foil 
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June 29. 1980 
CW & EQN 
FOIL 5 


Input: 

. EQ 

inf m sup k-1 


k -1 1-w 

Input: 

The equation $ f(t) ~ = ~ 2 pi 
int sin ( omega t ) dt $ 
is used here in running text, 
rather than being displayed. 

Output: 

The equation /(/) = 2tt Jsin(o>f )dt is 

used here in running text, rather than 
being displayed. 


sum from k=1 to 
-=- 1 over 1-m 

. EN 


Output: 


00 


k -1 


+ 


Fig. 5.5 — Example of Indent 
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June 29. 1980 
The Works: Input 
FOIL 6 


Input: 

.ts (- = tab) 

center doublebox ; 

Cip+4 ! Cip+4 S S 

* ! L L L 

* ! c ! c ! c 
''icicle 

Li i C i C i N . 

Users-»Hardware 

-»UNIX\* (Tm-»Model-»Ser ial 
-*System-»\ A -»Number 

OS Dev. -*A-»VAX+54 
SGS Dev. -+B-* 11/70-»3275 
Low-End-*C-* 11/23-»221 

And now . . . -»T { 

.NA 

Some filled text and an equation: 

T} -*T { 

$ zeta (s) = prod 

from k=1 to inf k sup -s $ 

.AD 

T} -»1.2 
.TE 



Fig. 5.6 — Example of Input of a Table Foil 
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June 29. I93C 
The Works: Ouipu: 

FOIL 7 


Output: 




Hardware 


Users 

UNIX™ 

System 

Model 

Serial 

Number 

OS Dev. 

A 

VAX 

54 

SGS Dev. 

B 

11/70 

3275 

Low-End 

C 

11/23 

221 

And now ... 

Some 
filled text 
and an 
equation: 

its )=n* _I 

t -1 

1.2 


Fig. 5.7 — Example of Output of a Table Foil 
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TABLE 5.A 


FOIL—START MACROS 


MACRO NAME 

SIZE* AND TYPE 

BTL FRAME NUMBERt 

.VS 

7x7 viewgraph or 
2x2 super-slide 

E-7351 or E-7351-R 

,Vw 

7x5 viewgraph 

E-7351-B 

.Vh 

5x7 viewgraph 

E-7351-A 

.VW 

9x7 viewgraph 

E-8814 or E-9148 

.VH 

7X9 viewgraph 

E-8814 or E-9148 

.Sw 

7x5 35mm slide 

E-7351-B 

.Sh 

5x7 35mm slide 

E-7351-A 

.SW 

9x7 35mm slide 

E-8814 or E-9148 

.SH 

7x9 35mm slide 

E-8814 or E-9148 


•Size of mounting frame opening (width times height) 
in inches. 


tBTL stock item number. 


TABLE 5.B 


DEFAULT POINT SIZE, DIMENSIONS, AND ASPECT RATIOS 


MACRO 

NAME POINT MAX. 

(NOTE 1) SIZE UNES 

NOMINAL 

ACTUAL (TEXT) 

1 

W H AR AR 

(NOTE 2) 

1 

W H AR AR 

(NOTE 2) 

.VS 18 21 

7 7 11 

6 6.8 1.13 .88 

.Vw 14 19 

.Vh 14 27 

.VW 14 21 

.VH 18 28 

7 5 .71 1.4 

5 7 1.4 .71 

7 5.4 .77 1.3 

7 9 1.3 .77 

6 4.8 .8 1.25 

4.2 6.8 1.6 .62 

6 5.2 .87 1.15 

6 8.8 1.5 .68 

.Sw 14 18 

.Sh 14 27 

.SW 14 18 

.SH 18 28 

7 4.6 .67 1.5 

4.6 7 1.5 .67 

7 4.6 .67 1.5 

6 9 1.5 .67 

6 4.4 .73 1.4 

3.8 6.8 1.8 .56 

6 4.4 .73 1.4 

5 8.8 1.76 .57 


Note 1: The .SW (if used as a viewgraph) and .VW foils must be enlarged by a 
factor of 9/7. 


Note 2: W—Width in inches. 

H—Height in inches. 
AR—Aspect ratio (H/W). 
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